HP OpenVMS Systems Documentation

HP Pascal for OpenVMS
User Manual

To eliminate duplication of programming and debugging efforts, OpenVMS systems provide many routines to perform common programming tasks. These routines are collectively known as system routines. They include routines in the run-time library to assist you in such areas as mathematics, screen management, and string manipulation. Also included are OpenVMS Record Management Services (RMS), which are used to access files and their records. There are also system services that perform tasks such as resource allocation, information sharing, and input/output coordination.

This chapter discusses the following topics:

• Section 6.1, Using System Definitions Files
• Section 6.2, Declaring System Routines
• Section 6.3, Calling System Routines
• Section 6.4, Using Attributes
• Section 6.5, Using Item Lists
• Section 6.6, Using Foreign Mechanism Specifiers on Actual Parameters
• Section 6.7, Using 64-Bit Pointer Types

Because all OpenVMS system routines adhere to the HP OpenVMS Calling Standard, you can declare any system routine as an external routine and then call the routine from an HP Pascal program.

6.1 Using System Definitions Files

To access system entry points, data structures, symbol definitions, and messages, HP Pascal provides files that you can inherit (.PEN) or include (.PAS) in your application. Table 6-1 summarizes the source and environment files that HP Pascal makes available to you in the directory SYS$LIBRARY (for instance, SYS$LIBRARY:STARLET.PEN).

For instance, the external routine declarations in STARLET define new identifiers by which you can refer to the routines. Example 6-1 shows that you can refer to SYS$HIBER as $HIBER if you use STARLET.

[INHERIT('SYS$LIBRARY:STARLET')] PROGRAM Suspend (INPUT,OUTPUT);
TYPE
   Sys_Time = RECORD
      I,J : INTEGER;
      END;
   Unsigned_Word = [WORD] 0..65535;
VAR
   Current_Time : PACKED ARRAY[1..80] OF CHAR;
   Length       : Unsigned_Word;
   Job_Name     : VARYING[15] OF CHAR;
   Ascii_Time   : VARYING[80] OF CHAR;
   Binary_Time  : Sys_Time;

BEGIN
{ Print current date and time }
$ASCTIM (TIMLEN := Length, TIMBUF := Current_Time);
WRITELN ('The current time is ', SUBSTR(Current_Time, 1, Length);

{ Get name of process to suspend }
WRITE ('Enter name of process to suspend: ');
READLN (Job_Name);

{ Get time to wake process }
WRITE ('Enter time to wake process: ');
READLN (Ascii_Time);

{ Convert time to binary }
IF NOT ODD ($BINTIM (Ascii_Time, Binary_Time))
THEN
   BEGIN
      WRITELN ('Illegal format for time string');
      HALT;
   END;

{ Suspend process }
IF NOT ODD ($SUSPND (PRCNAM := Job_Name))
THEN
   BEGIN
      WRITELN ('Cannot suspend process');
      HALT;
   END;

{ Schedule wakeup request for self }
IF ODD ($SCHDWK (DAYTIME := Binary_Time))
THEN
   $HIBER { Put self to sleep }
ELSE
   BEGIN
      WRITELN ('Cannot schedule wakeup');
      WRITELN ('Process will resume immediately');
   END;

{ Resume process }
IF NOT ODD ($RESUME (PRCNAM := Job_Name))
THEN
   BEGIN
      WRITELN ('Cannot resume process');
      HALT;
   END;
END.

Before calling a routine, you must declare it. System routine names conform to one of the two following conventions:

[[facility-code]]$procedure-name

For example, LIB$PUT_OUTPUT is the run-time library routine used to write a record to the current output device and $ASCTIM is a system service routine used to convert binary time to ASCII time.

Because system routines are often called from condition handlers or asynchronous trap (AST) routines, you should declare system routines with the ASYNCHRONOUS attribute.

Each system routine is documented with a structured format in the appropriate OpenVMS reference manual. The documentation for each routine describes the routine's purpose, the declaration format, the return value, and any required or optional parameters. Detailed information about each parameter is listed in the description. The following format is used to describe each parameter:

    parameter-name
    OpenVMS Usage :     OpenVMS data type
    type          :     parameter data type
    access        :     parameter access
    mechanism     :     parameter-passing mechanism

Using this information, you must determine the parameter's data type (type), the parameter's passing semantics (access), the mechanism used to pass the parameter (mechanism), and whether the parameter is required or optional from the call format.

The following sections describe the methods available in HP Pascal to obtain the various data types, access methods, and passing mechanisms.

6.2.1 Methods Used to Obtain OpenVMS Data Types

The data specified by a parameter has a data type. Several OpenVMS standard data types exist. A system routine parameter must use one of these data types.

For More Information:

• On OpenVMS data types and equivalent HP Pascal declarations (HP OpenVMS Calling Standard)

The access method describes the way in which the called routine accesses the data specified by the parameter. The following three methods of access are the most common:

• Read only---data must be read by the called routine. The called routine does not write the input data. Thus, input data supplied by a variable is preserved when the called routine completes execution.
• Write only---data that the called routine returns to the calling routine must be written into a location where the calling routine can access it. Such data can be thought of as output data. The called routine does not read the contents either before or after it writes into the location.
• Modify---a parameter specifies data that is both read and written by the called routine. In this case, the called routine reads the input data, which it uses in its operations, and then overwrites the input data with the results. Thus, when the called routine completes execution, the input data specified by the argument is lost.

Table 6-2 lists all access methods that may appear under the access entry in a parameter description, as well as the HP Pascal translation.

The way in which an argument specifies the actual data to be used by the called routine is defined in terms of the parameter-passing mechanism.

Table 6-3 lists all passing mechanisms that may appear under the mechanism entry in an argument description and the method used in HP Pascal to obtain the passing mechanism.

Parameters passed by reference and used solely as input to a system service should be declared with HP Pascal value semantics; this allows actual parameters to be compile-time and run-time expressions. When a system service requires a formal parameter with a mechanism specifier, you should declare the formal parameter with the READONLY attribute to specify value semantics. Other parameters passed by reference should be declared with HP Pascal variable semantics to ensure that the output data is interpreted correctly. In some cases, by reference parameters are used for both input and output and should also be declared with variable semantics.

The following example shows the declaration of the Convert ASCII String to Binary Time (SYS$BINTIM) system service and a corresponding function designator:

TYPE
   $QUAD = [QUAD,UNSAFE] RECORD
              L0 : UNSIGNED;
              L1 : INTEGER;
           END;

VAR
   Ascii_Time  : VARYING[80] OF CHAR;
   Binary_Time : $QUAD;

[ASYNCHRONOUS,EXTERNAL(SYS$BINTIM)] FUNCTION $BINTIM
   (TIMBUF : [CLASS_S] PACKED ARRAY [$l1..$u1:INTEGER] OF CHAR;
   VAR TIMADR : [VOLATILE] $QUAD)
   : INTEGER; EXTERNAL;
{In the executable section:}
IF NOT ODD ($BINTIM(Ascii_Time, Binary_Time))
THEN
   BEGIN
      WRITELN ('Illegal format for time string');
      HALT;
   END;

The first formal parameter requires the address of a character-string descriptor with value semantics; the second requires an address and uses variable semantics to manipulate the parameter within the service. Because you can call $BINTIM from a condition handler or AST routine, you should declare it with the ASYNCHRONOUS attribute. Also, because you may want to pass a volatile variable to the TIMADR parameter, you should use the VOLATILE attribute to indicate that the argument is allowed to be volatile.

6.2.4 Data Structure Parameters

Some system services require a parameter to be the address of a data structure that indicates a function to be performed or that holds information to be returned. Such a structure can be described as a list, a control block, or a vector. The size and POS attributes provide an efficient method of laying out these data structures. The size attributes ensure that the fields of the data structure are of the size required by the system service, and the POS attribute allows you to position the fields correctly.

For example, the Get Job/Process Information (SYS$GETJPIW) system service requires an item list consisting of an array of records of 12 bytes, where all but the last array cell requests one piece of data and the last array cell represents the item list terminator. By packing the record, you can guarantee that the fields of each record are allocated contiguously. Example 6-2 uses the system service routine $GETJPIW to retrieve the process's name as a 12-byte string.

[INHERIT('SYS$LIBRARY:STARLET')] PROGRAM Userid( OUTPUT );

TYPE
   Uword       = [WORD] 0..65535;
   Itmlst_Cell = PACKED RECORD
                    CASE INTEGER OF
                       1 : (Buf_Len   : Uword;
                            Item_Code : Uword;
                            Buf_Addr  : INTEGER;
                            Len_Addr  : INTEGER);
                       2 : (Term      : INTEGER);
                 END;
VAR
   Username_String   : [VOLATILE] VARYING [12] OF CHAR;
   Itmlst            : ARRAY [1..2] OF Itmlst_Cell := ZERO;
BEGIN
Itmlst[1].Buf_Len := 12;                    { 12 bytes returned }
Itmlst[1].Item_Code := JPI$_USERNAME;       { return user name }
Itmlst[1].Buf_Addr :=                       { store returned name here }
   IADDRESS(Username_String.BODY);
Itmlst[1].Len_Addr :=                       { store returned length here }
   IADDRESS(Username_String.LENGTH);
Itmlst[2].Term := 0;                        { terminate item list }

IF NOT ODD( $GETJPIW(,,,Itmlst) )
THEN
   WRITELN('error')
ELSE
   WRITELN('user name is ',Username_String);
END.

For More Information:

• On size attributes (HP Pascal for OpenVMS Language Reference Manual)

In some cases, you do not have to supply actual parameters to correspond to all the formal parameters of a system service. In HP Pascal, you can supply default values for such optional parameters when you declare the service. You can then omit the corresponding actual parameters from the routine call. If you choose not to supply an optional parameter, you should initialize the formal parameter with the appropriate value using the by immediate value (%IMMED) mechanism. The correct default value is usually 0.

For example, the Cancel Timer (SYS$CANTIM) system service has two optional parameters. If you do not specify values for them in the actual parameter list, you must initialize them with zeros when they are declared. The following example is the routine declaration for SYS$CANTIM:

[ASYNCHRONOUS,EXTERNAL(SYS$CANTIM)] FUNCTION $CANTIM (
        %IMMED REQIDT : UNSIGNED := %IMMED 0;
        %IMMED ACMODE : UNSIGNED := %IMMED 0) : INTEGER; EXTERNAL;

A call to $CANTIM must indicate the position of omitted parameters with a comma, unless they all occur at the end of the parameter list. For example, the following are legal calls to $CANTIM using the previous external declaration:

$CANTIM (, PSL$C_USER);
$CANTIM (I);
$CANTIM;

PSL$C_USER is a symbolic constant that represents the value of a user access mode, and I is an integer that identifies the timer request being canceled. If you call $CANTIM with both of its default parameters, you can omit the actual parameter list completely.

When it is possible for the parameter list to be truncated, you can also specify the TRUNCATE attribute on the formal parameter declaration of the optional parameter. The TRUNCATE attribute indicates that an actual parameter list for a routine can be truncated at the point that the attribute was specified. However, once one optional parameter is omitted in the actual parameter list, it is not possible to specify any optional parameter following that. For example:

[ASYNCHRONOUS] FUNCTION LIB$GET_FOREIGN (
   VAR Resultant_String : [CLASS_S,VOLATILE]
           PACKED ARRAY [$l1..$u1:INTEGER] OF CHAR;
       Prompt_String    : [CLASS_S,TRUNCATE]
           PACKED ARRAY [$l2..$u2:INTEGER] OF CHAR := %IMMED 0;
   VAR Resultant_Length : [VOLATILE,TRUNCATE] $UWORD := %IMMED 0;
   VAR Flags            : [VOLATILE,TRUNCATE] UNSIGNED := %IMMED 0)
           : INTEGER; EXTERNAL;

With this declaration, it is possible to specify values for Resultant_String and Prompt_String and truncate the call list at that point. In this case, two parameters would be passed in the CALL instruction.

You may want to use a combination of the %IMMED 0 and TRUNCATE methods. This combination would allow you to skip the specification of intermediate optional parameters, as well as allow you to truncate the call list once all desired parameters have been specified.

Note that OpenVMS system services require a value to be passed by parameters, including optional parameters; therefore, you should not use the TRUNCATE attribute when defining optional parameters to a system service. Instead, you should specify default values on the formal parameter declaration.

The TRUNCATE attribute is useful when calling routines for which the optional parameter is truly optional, for example, when calling run-time library routines.

For More Information:

• On the TRUNCATE attribute (HP Pascal for OpenVMS Language Reference Manual)