1 Pascal_Users

Digital provides hundreds of Run-Time Library (RTL) and Utility routines
that  are  callable  from  user programs written in almost any language.
There  are  routines  to  perform  a  great  variety  of tasks including
sophisticated  mathematical procedures, file and data manipulation, text
handling,   program-callable   file   editing,  system  interfacing  and
information requests, screen management and hardware instructions.

To  use  these  routines  in Pascal, it is necessary to provide EXTERNAL
declarations  for  them, as well as some associated TYPE definitions and
CONSTANT declarations.

PASLIB  has  been  developed  to  allow  Pascal programmers to take full
advantage of these routines which increase the ease of use, and scope of
application  of  the language.  In combination with the Digital-supplied
programming  language  facilities such as STARLET,  PASLIB  provides the
Pascal programmer with a comprehensive  environment for both application
and systems programming.  It is usual to INHERIT environment files which
contain  the  appropriate  declarations  for the programming environment
concerned.  The files available in STARLET are detailed in the HELP sub-
topic entitled Source_Code.

All available Run-Time Library and Utility routines that are not already
available  in  Digital-supplied  software  are declared in PASLIB.  Some
routines  have been omitted where the same functionality is available in
intrinsic  Pascal  functions.   These intrinsic functions should be used
in preference to any equivalent RTL or Utility routines.  

2 Contents

PASLIB contains declarations/definitions for the following:

PAS$     - Pascal file routines, condition codes and status values.
SYS$     - system service definitions missing from STARLET.

2 Examples

The  following  examples show the principles of using PASLIB and STARLET
in the context of System Services, RTL and Utility routines.  For a full
description  of  the  routines  used, refer to the manuals listed in the
"Further_Information" section of this HELP information.


 1. The  following  program example shows the use of the MTH$RANDOM  RTL
    routine and the $GETTIM system service.


    [ INHERIT ('SYS$LIBRARY:STARLET',
               'SYS$LIBRARY:PASCAL$LIB_ROUTINES',
               'SYS$LIBRARY:PASCAL$MTH_ROUTINES') ]

    PROGRAM  Pick_A_Number (OUTPUT) ;  { Pick an integer; 0 <= n < 100 }

    VAR  Rst : UNSIGNED := 0 ;      { Return Status from routine call }
         Number : INTEGER := 0 ;    { Our generated random integer }
         Time_Now : RECORD          { Current time as a quad-word }
                      Seed , Chaff : UNSIGNED ;
                    END ;

    BEGIN
    Rst := $GETTIM (Time_Now) ;     { Get current time as a quad-word }
    IF NOT ODD (Rst)  THEN
       LIB$SIGNAL (Rst) ;           { Signal any error returned }
    Number := MTH$RANDOM (Time_Now.Seed) * 100 ;
    WRITELN ('The number is ',Number:1) ;
    END.


 2. The  following  program  shows  how  to  use the LIB$DAY_OF_WEEK RTL
    function.    LIB$DAY_OF_WEEK  takes  a  system  time  as  its  first
    parameter,  passed  by  reference.    Either a variable containing a
    valid  quad-word  system time or the value zero (meaning the current
    system time) may be passed.  If the value zero is passed, it must be
    passed  by  immediate  value,  not  by reference.  Consequently, the
    %IMMED  foreign  mechanism specifier must be specified on the actual
    value.


    [ INHERIT ('SYS$LIBRARY:STARLET',
               'SYS$LIBRARY:PASCAL$LIB_ROUTINES') ]

    PROGRAM  What_Day (OUTPUT) ;

    VAR  Rst ,                       { Return Status from routine call }
         Day_Num : UNSIGNED := 0 ;

    BEGIN
    Rst := LIB$DAY_OF_WEEK (%IMMED 0,Day_Num) ;
    IF NOT ODD (Rst)  THEN
       LIB$SIGNAL (Rst)              { Signal any error returned }
     ELSE
       WRITELN ('Today is ',Day_Num:1) ;
    END.


 3. The  following  program  shows the use of different string parameter
    types to the same routine.


    [ INHERIT ('SYS$LIBRARY:STARLET',
               'SYS$LIBRARY:PASCAL$LIB_ROUTINES',
               'SYS$LIBRARY:PASCAL$STR_ROUTINES') ]

    PROGRAM String_Example (OUTPUT) ;

    VAR  Rst : UNSIGNED := 0 ;
         Start_Pos , End_Pos : INTEGER := 0 ;

         V_Dest , Src_Str , Rpl_Str : VARYING [20] OF CHAR := '' ;
         P_Dest : PACKED ARRAY [1..20] OF CHAR := '' ;

    BEGIN
    Src_Str := 'How can this be?' ;
    Rpl_Str := 'izz' ;
    Rst := STR$REPLACE (V_Dest,Src_Str,5,7,Rpl_Str) ;
    IF Rst <> SS$_NORMAL  THEN
       LIB$SIGNAL (Rst)
     ELSE
       WRITELN (V_Dest) ;  { ==> 'How izz this be?' }

    Src_Str := 'Why is it so?' ;
    Rpl_Str := 'iz' ;
    Start_Pos := 5 ;
    End_Pos := 6 ;
    Rst := STR$REPLACE (%STDESCR P_Dest,Src_Str,
                                 Start_Pos,End_Pos,Rpl_Str) ;
    IF Rst <> SS$_NORMAL  THEN
       LIB$SIGNAL (Rst)
     ELSE
       WRITELN (P_Dest) ;  { ==> 'Why iz it so?' }
    END.


 4. The  following  program  statements  show  the use of positional and
    non-positional syntax.


    VAR  Rst ,        { Return status from RTL routine invocation }
         Paste_Board : UNSIGNED := 0 ;   { New pasteboard id. }

    Rst := SMG$CREATE_PASTEBOARD (Paste_Board,Flags:=0) ;

    Rst := SMG$DELETE_PASTEBOARD (Paste_Board) ;

    Rst := SMG$CREATE_PASTEBOARD (Paste_Board,,,,0) ;


2 Further_Information

The following on-line sources and printed manuals provide significant
additional information:


On-line HELP:     (Enter  $ HELP topic )

$ HELP PASCAL
$ HELP Pascal_Users            ! (Produces this HELP information)
$ HELP RTL_Routines
$ HELP System_Services

Printed Manuals:  (Copies kept by I.T.S. HotLine)

DEC System Services Manual
DEC Run-Time Library Routines Manuals
DEC Pascal Reference Manual
DEC Pascal User Manual

2 How_To_Use

PASLIB  may be used by INHERITing the PASLIB environment file as follows
at the top of a Pascal program or module:

  [ INHERIT ('SYS_LIBRARY:PASLIB') ]

STARLET  may  be  used  by  INHERITing  the  STARLET environment file as
follows at the top of a Pascal program or module:

  [ INHERIT ('SYS$LIBRARY:STARLET') ]

To use both PASLIB and STARLET, combine the two INHERITs as follows:

  [ INHERIT ('SYS$LIBRARY:STARLET','SYS_LIBRARY:PASLIB') ]

To use both PASLIB and other STARLET environments, use INHERITs as
appropriate as in the example that follows:

    [ INHERIT ('SYS$LIBRARY:STARLET',
               'SYS_LIBRARY:PASLIB',
               'SYS$LIBRARY:PASCAL$LIB_ROUTINES',
               'SYS$LIBRARY:PASCAL$OTS_ROUTINES') ]


2 Implementation_Conventions

Digital automatically generate the Pascal source code for STARLET from a
general description of the contents of STARLET which is used to generate
similar  code  for other programming languages.  The conventions used to
generate  the  Pascal source may not always be considered to be the most
suitable  implementation  for  some  Pascal  users.    In order that any
transition  from  using  PASLIB to using STARLET (as more information is
incorporated  into  STARLET in future releases) may be as transparent as
possible,  similar  implementation  conventions  have  been  adopted  in
PASLIB.

Some  features of the implementation of PASLIB are noted below.  Some of
these features differ from the conventions used in STARLET:

-  All  routine  names  are  the same  as indicated  in the  VMS  system
   routines  manuals,  with  the  exception  of  a  few  routines  whose
   parameters  may  be  of different data types depending on the program
   context.    In  particular, these exceptions are in the LBR$ facility
   where  any  routine  of the form LBR$xxxxxx_KEY will be of either the
   form LBR$xxxxxx_KEY_A if the Key is ASCII, or LBR$xxxxxx_KEY_B if the
   Key  is  binary.    Refer  to  the  LBR$  documentation  for  further
   information.

-  All  formal  parameter names are  the same  as indicated  in  the VMS
   system  routines manuals, with the exception of a few names which are
   reserved words in Pascal and which cannot be re-declared as variables
   (e.g.  "Record"); these parameters have an underscore ("_") prepended
   to  the indicated name (e.g. "_Record").  This allows the free use of
   non-positional syntax if desired.

-  Formal  parameter  lists  for formal routine parameters have not been
   declared.    This may mean an Informational message will be generated
   by the compiler if the passed routine itself passes parameters.  This
   should not affect the working of the program.

-  Actual  string  parameters passed as READONLY may be any valid string
   expression or variable.

-  In most cases, actual string parameters passed as WRITEONLY or MODIFY
   are  presumed to be of type VARYING OF CHAR.  In some cases, a string
   passed  by  "fixed length descriptor" is required; a variable of type
   PACKED  ARRAY  OF  CHAR must be passed.  In neither case can a string
   expression be passed.  Where the formal parameter is declared as type
   VARYING  OF  CHAR  and  it is desired to pass a PACKED ARRAY OF CHAR,
   this  can  be  done  by  specifying  the  %STDESCR  foreign mechanism
   specifier on the actual parameter (see the "Examples" section in this
   HELP information).

2 Missing_Symbols

There  are  some  symbolic  constants  which  are not declared in either
PASLIB  or  STARLET.    In particular, condition code values for several
facilities  (e.g.  LBR$)  are not included.  It is possible, however, to
use  such  constants  in  a  Pascal program without knowing their actual
values.    This  is done by declaring a VARIABLE of the same name as the
constant,  with  the  attributes  EXTERNAL and VALUE.  The variable type
must  be  appropriate  to  the  constant  value's  type.  Generally, for
condition code values and the like, type UNSIGNED should be used.

For  example,  to  reference  the  symbolic  constants  LBR$_ILLFMT  and
LBR$_NOFILNAM in a program which uses the LBR$ Utility routines, declare
variables as follows:

    VAR  LBR$_ILLFMT , LBR$_NOFILNAM : [EXTERNAL,VALUE] UNSIGNED ;

These "variables" will be treated as READONLY constants whose values are
specified in a system library  referenced  at  link time.  At link time,
link against the appropriate system symbol table (usually) as follows:

    $ LINK  /SYSEXE  MYPROG,SYS$LOADABLE_IMAGES:SYSDEF.STB/SELECT

If  constants  which  must  be declared this way are at some future date
incorporated  into  either STARLET or PASLIB, these program declarations
may simply be removed when the program is re-compiled to obtain the same
functionality.    (This  assumes  that  the  program INHERITs STARLET or
PASLIB (or both) as appropriate.)

2 Problems_and_Enquiries

All  enquiries  and  problems  should be directed to the I.T.S. HotLine
(ext. 4488).

2 Source_Code

The complete Pascal source code for STARLET is in the following files:

     SYS$LIBRARY:STARLET.PAS
     SYS$LIBRARY:PASCAL$*_ROUTINES.PAS

The Pascal source code for the elements of PASLIB is in the single file

     SYS_LIBRARY:PASLIB.SRC

N.B.  These  sources do  NOT need to be used in programs.  They are for
      reference  only.  This source for PASLIB is not  compilable as it
      appears here.

2 STARLET_Modules

STARLET  is  a  Digital-supplied  facility  to  enable  VMS  programming
languages  to have access to system constants, data types and  routines.
In the case of  Pascal,  STARLET  is  usually  used  by  INHERITing  the
required STARLET environment file(s) in each program or module that uses
any system elements which are not intrinsic to Pascal.

In  theory,  STARLET  should  provide  most,  if not all the information
contained in PASLIB.  However, at the moment, PASLIB supplies the (quite
significant)  information  that, as yet, Digital have not implemented in
STARLET.   As this information is gradually incorporated into STARLET in
new  releases,  the corresponding information in PASLIB will be removed.

For  examples  of the use of STARLET and PASLIB, refer to the "Examples"
section in this HELP information.
