Using PL/I in the Common Language Environment

When you write a parameter descriptor for a non-PL/I procedure, you can specify the ANY attribute without the VALUE attribute to describe an argument that is to be passed by reference. The argument can be of any addressable data type known to PL/I. For example, the SYS$READEF service can be specified as follows:

DECLARE SYS$READEF ENTRY (FIXED BINARY(31) VALUE, ANY);

The second parameter descriptor in the ENTRY attribute indicates that the second argument is to be passed by reference to the procedure SYS$READEF and that it can have any data type. When you specify ANY for an argument to be passed by reference, you cannot specify data type attributes. Note that if you specify the VALUE attribute in conjunction with the ANY attribute, PL/I passes the argument by value.

The ANY attribute is especially useful when you must specify a data structure as an argument. You need not declare the structure within the parameter descriptor, only the ANY attribute.

When PL/I passes an argument by reference, it places either the address of the actual argument or the address of a dummy argument in the argument list of the called procedure. PL/I creates a dummy argument in the following cases:

In the last case listed above, PL/I issues an informational or warning message and, for scalar arguments, creates a dummy argument of the data type of the parameter. It places the address of this dummy argument in the argument list. If the argument is an aggregate, PL/I issues an error message; it does not create a dummy argument for an array or for a structure.

In creating a dummy argument, PL/I performs the following conversions:

In all other cases, the data type of the dummy argument is the same as the data type of the written argument.

When an argument is passed by reference, PL/I places the address of the actual argument in the argument list. This address can be interpreted as a pointer value. In fact, you can explicitly specify a pointer value as an argument for data to be passed by reference. For example:

DECLARE SYS$READEF (ANY VALUE, POINTER VALUE),
        FLAGS BIT(32) ALIGNED;
CALL SYS$READEF (4, ADDR(FLAGS));

At this procedure invocation, PL/I places the pointer value returned by the ADDR built-in function directly in the argument list.

Figure 11.5, “Passing a Pointer Value as an Argument (VAX)” illustrates the argument list for the following example. Note that the actual argument list in this example corresponds to the argument list shown previously in Figure 11.4, “Argument Passing by Reference”. Note also that Figure 11.5, “Passing a Pointer Value as an Argument (VAX)” applies to the VAX platform only. Please see OpenVMS Calling Standard for equivalent information for the OpenVMS Alpha platform.

DECLARE FLAGS BIT(32) ALIGNED;
DECLARE SYS$READEF (ANY VALUE, POINTER VALUE),
     ⋮
CALL SYS$READEF(4,ADDR(FLAGS));

In FORTRAN, arrays must always be passed by reference; the array's extents are, by custom, passed as separate arguments. The REFERENCE attribute provides a convenient way to express an array parameter for FORTRAN. For example:

FTNARRAY: PROCEDURE(X);
DECLARE SUM ENTRY ((*) FLOAT REFERENCE, FIXED BINARY(31))
                    RETURNS (FLOAT);

DECLARE (S, X(*)) FLOAT;

S = SUM(X, DIM(X));

SUM is a FORTRAN routine that sums the elements of a one-dimensional array of floating-point numbers. Its second parameter is the number of elements in the array.

When you declare a non-PL/I routine that requires a character-string descriptor for an argument, specify the parameter descriptor as CHARACTER(*). For example, the Set Process Name system service (SYS$SETPRN) requires the address of a character-string descriptor as an argument. You can declare this service as follows:

DECLARE SYS$SETPRN ENTRY (CHARACTER(*) OPTIONAL);

When a parameter is declared as CHARACTER(*), its written argument can be one of the following:

For any of these arguments, PL/I constructs a character-string descriptor and places its address in the procedure's argument list.

If you specify a varying character-string argument for a parameter declared as (CHARACTER(*), the PL/I compilers issue a warning message, construct a fixed-length character-string dummy argument, and create a character-string descriptor for the dummy argument.

For an input argument, as in the example of the SYS$SETPRN service, the dummy argument is acceptable. To suppress the warning message during compilation, enclose the argument in parentheses. For example, if NAME is a variable declared with the CHARACTER VARYING attributes, you can specify it as an argument to the SYS$SETPRN system service like this:

CALL SYS$SETPRN ((NAME));

The parentheses around the argument NAME force PL/I to create a dummy argument. The compiler does not issue a warning about a nonmatching parameter and argument.

For a non-PL/I routine that returns a character string to a variable, however, you cannot use a varying character string for an argument. If the actual output argument is declared as VARYING and the parameter descriptor specifies CHARACTER(*), PL/I creates a dummy argument and the actual argument is not modified. Thus, for output character strings passed by character-string descriptor, you must choose one of the following:

In either case, you must include in your program the statements necessary to determine the length of the string returned. For example, the SYS$ASCTIM system service returns a character-string time value to a character-string descriptor and returns the length of the string to a fixed-point binary variable. These two arguments can be declared as follows:

DECLARE TIME CHARACTER(63),
        TIME_LENGTH FIXED BINARY(15);

After the call to this procedure, the following statement might output the equivalence name returned:

PUT LIST ('Time is ',SUBSTR(TIME,1,TIME_LENGTH));

The PUT statement uses the SUBSTR built-in function to obtain the length of the string returned in the variable TIME_LENGTH by SYS$ASCTIM.

You can use the ANY CHARACTER(*) declaration to declare parameters for routines that can handle both fixed- or varying-length strings for a single parameter. The declaration allows either VARYING or NONVARYING strings to be passed without the creation of a dummy argument. Essentially, all OpenVMS system routines, with the exception of the system services and Librarian Utility routines, can accept string parameters of this type.

Note that routines written in other languages do not allow strings to be passed using this method by default. The routine being called must explicitly use LIB$ANALYZE_SDESC (or an equivalent routine) for this declaration to work correctly.

You can use the ANY CHARACTER(*) attribute as shown in the following example:

%INCLUDE $STSDEF;
DECLARE FIXED_STRING CHAR(22),
        VARYING_STRING CHAR(80) VARYING;

DECLARE LIB$DATE_TIME ENTRY(
            ANY CHARACTER(*))
            RETURNS (FIXED BINARY(31));

STS$VALUE = LIB$DATE_TIME(FIXED_STRING);
STS$VALUE = LIB$DATE_TIME(VARYING_STRING);

In both of these cases, the string contains the output value, since no dummy argument is required.

The ANY and DESCRIPTOR attributes can be used together for routines that can process any valid data type descriptor. Routines of this type are few; however, LIB$CVT_DX_DX and the routine DTR$COMMAND in the DEC DATATRIEVE layered product callable interface allow any valid data type descriptor. For these routines, declarations should be as follows:

DECLARE LIB$CVT_DX_DX ENTRY(
                ANY DESCRIPTOR,
                ANY DESCRIPTOR,
                FIXED BINARY(15) OPTIONAL TRUNCATE)
              RETURNS(FIXED BINARY(31));

DECLARE DTR$COMMAND ENTRY(
                1 LIKE DTR_ACCESS_BLOCK,
                ANY CHARACTER(*),
                ANY DESCRIPTOR LIST TRUNCATE);

To pass an actual descriptor as an argument, you must take the following steps; the keyed numbers correspond to the callout numbers in Example 11.1, “Writing a Character-String Descriptor”.

The Set Process Name system service (SYS$SETPRN) shown in Example 11.1, “Writing a Character-String Descriptor” requires a text name string to be passed by descriptor. The structure variable NAME_DESC is a character-string descriptor; its members describe the length and location of the character-string variable NEWNAME. The value of NEWNAME is the actual argument passed to the procedure. Note that the call in this example is equivalent to the example shown in Figure 11.6, “Argument Passing by Descriptor” of passing an argument by descriptor.

DECLARE SYS$SETPRN ENTRY (CHARACTER(*));❶

DECLARE 1 NAME_DESC,
          2 NAME_LENGTH FIXED BINARY (31),❷
          2 NAME_ADDRESS POINTER;

DECLARE NEWNAME CHARACTER (5) STATIC INITIAL ('ORION');
NAME_DESC.NAME_LENGTH = LENGTH(NEWNAME);❸
NAME_DESC.NAME_ADDRESS = ADDR(NEWNAME);❸

CALL SYS$SETPRN(REF(NAME_DESC));❹

Note that this example can be simplified if SYS$SETPRN is declared as follows:

DECLARE SYS$SETPRN ENTRY (ANY);

All other variables would be the same as in Example 11.1, “Writing a Character-String Descriptor”, although the use of the REFERENCE built-in function could be omitted.

In most cases, the first method is preferable because it allows the declarations in PLI$STARLET to be used consistently; the only cases in which special handling is required is for those calls that require it.

For arguments to be passed by value, PL/I always creates a dummy argument directly in the argument list for the called procedure. If the parameter descriptor is specified with the ANY and VALUE attributes, dummy arguments are created with the following data types:

If a parameter descriptor is specified as VALUE with a particular data type (as opposed to being specified as ANY), a dummy argument of that data type is always created, and the written argument is assigned to the dummy. The written argument must be valid for conversion to the data type specified in the corresponding parameter descriptor.

Although most system routines and procedures require a specific number of arguments, some routines accept an unspecified number of optional arguments. To declare these routines in a PL/I program so that you can invoke them with differing numbers of arguments, you must declare the last parameter with the LIST attribute. The last parameter descriptor given in the ENTRY attribute is used for extra arguments.

The Formatted ASCII Output system service (SYS$FAO) is an example of a procedure that has a variable-length argument list. It can be declared as follows:

DECLARE SYS$FAO ENTRY (CHAR(*), FIXED BINARY(15) OPTIONAL,
                    CHAR(*), ANY VALUE LIST TRUNCATE);

This parameter descriptor specifies only four arguments. When SYS$FAO is invoked with more than four arguments, PL/I uses the parameter descriptor of the last parameter (ANY VALUE) to pass all the additional arguments. If any argument that will be specified is not to be passed by value, you must specify a parameter descriptor for the argument in the declaration.

Some PL/I and non-PL/I routines with fixed-length argument lists accept optional arguments and provide a default action if no value is specified for the optional argument. When an optional argument is not specified, its corresponding argument list longword is filled with a value of zero passed by immediate value.

In PL/I , you can omit the specification of an optional argument in a written argument list as long as you enter the correct number of commas to ensure that the argument list will have the correct number of longwords. You can indicate that you are not specifying an optional argument in either of the following ways:

In the case of trailing arguments all of which have the OPTIONAL attribute, you do not need to specify the commas, although you might choose to do so to add clarity for people who read your source code. But if you do not specify commas, the compiler will automatically create null parameters for trailing formal parameters that have the OPTIONAL attribute, ensuring that any requirement for a minimum length argument vector is met, for instance in the case of VMS system services.

For example, an argument list that has three optional arguments can be written as follows:

(,,)

The called procedure must detect and interpret the optional parameters in the argument list. The following example illustrates optional arguments omitted from an argument list:

DECLARE SYS$ASCTIM ENTRY (
                       FIXED BINARY(15) OPTIONAL,
                       CHARACTER(*),
                       ANY OPTIONAL,
                       BIT(1) ALIGNED VALUE OPTIONAL),
        TIME_STRING CHARACTER(24);
⋮
CALL SYS$ASCTIM(,TIME_STRING,,);
⋮
CALL SYS$ASCTIM(,TIME_STRING);

This call to the service SYS$ASCTIM specifies only the second argument; the argument list contains four arguments. When you specify a null argument, as in either of the cases above, PL/I always places a zero in the argument list passed to the called procedure.

Some routines may allow an argument list to be truncated in a specified location. For example:

DECLARE LIB$GET_INPUT ENTRY (ANY CHARACTER(*),
                          ANY CHARACTER(*) OPTIONAL TRUNCATE,
                          FIXED BINARY(15) OPTIONAL TRUNCATE);

This declaration of the Get Line from SYS$INPUT routine (LIB$GET_INPUT) specifies that the argument list may vary in length. In fact, LIB$GET_INPUT has three parameters, but the last two parameters are optional.

When you invoke such a routine omitting trailing arguments, you do not have to account for all the arguments in the procedure invocation argument list. For example, the LIB$GET_INPUT routine can be invoked with trailing arguments omitted:

CALL LIB$GET_INPUT(GET_STRING);

The variable GET_STRING is specified for the first argument. The other two arguments are not specified. Unlike the case with the OPTIONAL attribute, the compiler will not create blank entries in the argument vector passed to the called program.

The default PL/I text library PLI$STARLET.TLB contains declarations for all the system routines as external entries. The text module names are most often the same as the routine entry points. Thus, to include the declaration of a system service you are going to use, you specify a %INCLUDE statement as in this example:

%INCLUDE SYS$TRNLNM;

The PL/I compilers, by default, locate the module SYS$TRNLNM in PLI$STARLET.TLB during compilation.

In PLI$STARLET.TLB, any system service that has a wait for event flag version is found in the same module as the version without the wait. Thus, to get the definition of any wait (“W”) form, you need to use the base (nonwait) form of the service in the %INCLUDE statement. For example, to get the definition for SYS$GETJPIW, you should use the following:

%INCLUDE SYS$GETJPI;

Global symbol definitions for the entry vectors of all system services are located in the default system object module library, STARLET.OLB, in SYS$LIBRARY. When you link a PL/I program, the linker searches this library by default.

All the system routine arguments are described in terms of the following information:

OpenVMS usages are data structures that are layered on the standard OpenVMS data types. For example, the OpenVMS usage mask_longword signifies an unsigned longword integer that is used as a bit mask, and the OpenVMS usage floating_point represents any OpenVMS floating-point data type. Table 11.6, “PL/I Implementation of OpenVMS Usages” lists all the OpenVMS usages and the PL/I statements you need to implement them. (The callout numbers in Table 11.6, “PL/I Implementation of OpenVMS Usages” are keyed to the list following the table.)

1 ACCESS_BIT_NAMES(32),
  2 LENGTH FIXED BINARY(15),
  2 DTYPE FIXED BINARY(7) 
    INITIAL((32)DSC$K_DTYPE_T),
  2 CLASS FIXED BINARY(7)
    INITIAL((32)DSC$K_CLASS_S), 
  2 CHAR_PTR POINTER;  ❻

1 ARG_LIST BASED,
  2 ARGCOUNT FIXED BINARY(31),
  2 ARGUMENT (X REFER (ARGCOUNT)) 
    POINTER;  ❻

(2) FLOAT BINARY(n) or 
1 CPLX,
  2 REAL FLOAT BIN(n), 
  2 IMAG FLOAT BIN(n); 
(See floating_point for values of n.)

1 EXIT_HANDLER_BLOCK BASED,
  2 FORWARD_LINK POINTER,
  2 HANDLER POINTER,
2 ARGCOUNT FIXED BINARY(31),
  2 ARGUMENT (n REFER 
    (ARGCOUNT)) POINTER;  ❻
 Replace n with an expression that will yield a value between 0 and 255 at the time the structure is allocated. 

Because there are different formats for I/O status blocks for various system services, different definitions will be appropriate for different uses. Some of the common formats are shown here.  ❻ 

1 IOSB_SYS$GETSYI,
  2 STATUS FIXED BINARY(31),
  2 RESERVED FIXED BINARY(31); 

1 IOSB_TTDRIVER_A,
  2 STATUS FIXED BINARY(15), 
  2 BYTE_COUNT FIXED BINARY(15),
  2 MBZ FIXED BINARY(31) INITIAL(0);
 
1 IOSB_TTDRIVER_B,
  2 STATUS FIXED BINARY(15),
  2 TRANSMIT_SPEED FIXED 
    BINARY(7), 
  2 RECEIVE_SPEED FIXED BINARY(7), 
  2 CR_FILL FIXED BINARY(7),
  2 LF_FILL FIXED BINARY(7),
  2 PARITY_FLAGS FIXED BINARY(7),
  2 MBZ FIXED BINARY(7) INITIAL(0);

1 ITEM_LIST_2,
  2 ITEM(SIZE), 
    3 COMPONENT_LENGTH FIXED
      BINARY(15), 
    3 ITEM_CODE FIXED BINARY(15), 
    3 COMPONENT_ADDRESS
      POINTER, 
  2 TERMINATOR FIXED BINARY(31) 
    INITIAL(0);  ❻ 

Replace SIZE with the number of items you want.

1 ITEM_LIST_3,
  2 ITEM(SIZE), 
    3 BUFFER_LENGTH FIXED
      BINARY(15), 
    3 ITEM_CODE FIXED BINARY(15), 
    3 BUFFER_ADDRESS POINTER, 
    3 RETURN_LENGTH POINTER, 
  2 TERMINATOR FIXED BINARY(31) 
    INITIAL(0);  ❻ 

Replace SIZE with the number of items you want.

1 ITEM_LIST_PAIR,
  2 ITEM(SIZE), 
    3 ITEM_CODE FIXED BINARY(31),
    3 ITEM UNION, 
      4 INTEGER FIXED BINARY(31),
      4 REAL FLOAT BINARY(24),
  2 TERMINATOR FIXED BINARY(31) 
    INITIAL(0);  ❻ 

Replace SIZE with the number of items you want.

1 ITEM_QUOTA_LIST,
  2 QUOTA(SIZE), 
    3 NAME FIXED BINARY(7),
    3 VALUE FIXED BINARY(31),
  2 TERMINATOR FIXED BINARY(7) 
    INITIAL(PQL$_LISTEND);  ❻

Replace SIZE with the number of quota entries that you want to use. The constant PQL$_LISTEND can be used by including the module $PQLDEF from PLI$STARLET or by declaring it GLOBALREF FIXED BINARY(31) VALUE.

1 LOCK_STATUS_BLOCK,
  2 STATUS_CODE FIXED BINARY(15),
  2 RESERVED FIXED BINARY(15), 
  2 LOCK_ID FIXED BINARY(31);  ❻

1 RIGHTS_HOLDER,
  2 RIGHTS_ID FIXED BINARY(31),
  2 ACCESS_RIGHTS BIT(32) 
    ALIGNED;  ❻

If a system routine argument is optional, it will be indicated in the format section of the routine description in one of two ways:

If the comma appears outside the brackets, you must either pass a zero by value or use a comma in the argument list as a placeholder to indicate the place of the omitted argument. If this is the last argument in the list, you do not need to include the comma as a placeholder, as the PL/I compilers will pass a zero by value for the argument, fulfilling any minimum argument vector length requirements, for instance in the case of VMS system services. Otherwise, you can use a comma in the argument list as a placeholder, and the PL/I compilers will pass a zero by value for the argument.

To determine the PL/I parameter descriptors in the declaration of a given system routine, you can display or print the text module for that routine. For example:

$ LIBRARY/EXTRACT=SYS$TRNLNM/OUTPUT=LP:TRNLNM -
_$ SYS$LIBRARY:PLI$STARLET/TEXT

This LIBRARY command prints the contents of the text module SYS$TRNLNM from the library SYS$LIBRARY:PLI$STARLET. The file is printed on the device LP; the listing file is named TRNLNM.TXT.

Many system routines depend on values that are defined in separate symbol definition files. OpenVMS Run-Time Library routines require you to include symbol definitions when you are calling a Screen Management facility routine or a routine that is a jacket to a system service. A jacket routine provides a simpler interface to the corresponding system service. For example, the routine LIB$SYS_ASCTIM is a jacket routine for the $ASCTIM system service.

If you are calling a system service, you must include the module $SSDEF to check status. Many system services require other symbol definitions as well. To determine whether you need to include other symbol definitions for the system service you want to use, refer to the documentation for that particular system service. If the documentation states that values are defined in a macro, you must include those symbol definitions in your program.

For example, the description for the flags parameter in the SYS$MGBLSC (Map Global Section) system service states that “Symbolic names for the flag bits are defined by the $SECDEF macro.” Therefore, when you call SYS$MGBLSC you must include the definitions provided in the $SECDEF module.

A definition module is included as follows:

%INCLUDE $SSDEF;

You can declare the names of global symbols using the GLOBALREF and VALUE attributes. Then, you can use the names to represent values in an argument list to invoke a system service. For symbolic names that are not defined as OpenVMS global symbols, PL/I provides text modules in the default INCLUDE library PLI$STARLET.

The names of the text modules, and the names and values of the symbols defined in each, are the same as the MACRO definitions in the system macro library, STARLET.MLB.

Example 11.3, “Creating a Mailbox” illustrates a call to the Create Mailbox and Assign Channel (SYS$CREMBX) system service. This service returns the number of an I/O channel to the calling program. In PL/I, this number is not needed except for the deletion of the mailbox. You must, however, declare a FIXED BINARY(15) variable to receive the number returned by the system service. The following notes are keyed to Example 11.3, “Creating a Mailbox”:

CREATE_MAILBOX: PROCEDURE OPTIONS(MAIN) RETURNS(FIXED BINARY(31));

    %INCLUDE SYS$CREMBX;
    %INCLUDE $STSDEF;
    %REPLACE MESSAGE_SIZE BY 132;
    %REPLACE PERMANENT BY '1'B;

    DECLARE
        CHANNEL FIXED BINARY(15),
        MAILBOX_NAME CHARACTER(11)
                    STATIC INITIAL('PLI_MAILBOX');
    /*
     * Call SYS$CREMBX omitting optional arguments.
     * (Note that trailing optional arguments cannot
     * be omitted for system services unless specifically
     * indicated in the service description.)
     */
    STS$VALUE = SYS$CREMBX(                              ❶
                        PERMANENT,                       ❷
                        CHANNEL,
                        MESSAGE_SIZE,                    ❸
                        'FF00'B4,,                       ❹
                        MAILBOX_NAME);
    /*
     * Return to command level with status. If SYS$CREMBX
     * completed with an error, the appropriate message is
     * displayed at the command level.
     */
    RETURN(STS$VALUE);
    END CREATE_MAILBOX;

Example 11.4, “Deleting a Mailbox” illustrates a call to the Delete Mailbox (SYS$DELMBX) system service. The procedure DELETE_MAILBOX deletes the mailbox PLI_MAILBOX. A mailbox is deleted when a channel number is specified; this program assigns a channel to the mailbox to obtain a number to be specified in deleting the mailbox. The following notes are keyed to Example 11.4, “Deleting a Mailbox”:

DELETE_MAILBOX: PROCEDURE OPTIONS(MAIN) RETURNS(FIXED BINARY(31));

    %INCLUDE SYS$ASSIGN;                               ❶
    %INCLUDE SYS$DELMBX;
    %INCLUDE $STSDEF;

    DECLARE
        MAILBOX_NAME CHARACTER(11)
                STATIC READONLY INITIAL('PLI_MAILBOX')
        CHANNEL FIXED BINARY(15);
    /*
     * Call SYS$ASSIGN and check return; if not successful exit
     */
    STS$VALUE = SYS$ASSIGN(MAILBOX_NAME,CHANNEL,,,);   ❷
    IF ^STS$SUCCESS
    THEN
       RETURN(STS$VALUE);
    /*
     * Call SYS$DELMBX and check return
     */
    STS$VALUE = SYS$DELMBX(CHANNEL);                   ❸
    RETURN(STS$VALUE);

    END DELETE_MAILBOX;

The PL/I procedure GETBINTIM, shown in Example 11.5, “Obtaining a System Time Value”, accepts a character-string time value as a parameter and returns the binary time value to the point of the procedure's invocation. The following notes are keyed to Example 11.5, “Obtaining a System Time Value”:

This procedure may be invoked as follows to supply a date and time value for a file in an ENVIRONMENT option:

DECLARE GETBINTIM ENTRY( CHAR(*) ) RETURNS BIT(64) ALIGNED,
        (CREATED_DATE,EXPIRE_DATE) BIT(64) ALIGNED;

    CREATED_DATE = GETBINTIM('17-JUN-1985 00:00:00.00');
    EXPIRE_DATE = GETBINTIM('31-DEC-1991 00:00:00.00');
    OPEN FILE(TAPEFILE) ENVIRONMENT(

           CREATION_DATE(CREATED_DATE),
           EXPIRATION_DATE(EXPIRE_DATE));

/*
 *  This procedure converts a time given in ASCII format to a
 *  64-bit time value that is used internally by OpenVMS.
 *  Input strings must be of the form:
 *
 *  dd-mmm-yyyy-hh:mm:ss.cc (for an absolute date or time)
 *  dddd hh:mm:ss.cc        (for a delta time)
 */
GETBINTIM: PROCEDURE(ASCII_STRING) RETURNS(BIT(64) ALIGNED);

    %INCLUDE SYS$BINTIM;                               ❶
    %INCLUDE $STSDEF;

    DECLARE
        ASCII_STRING CHARACTER(*),
        BINARY_TIME BIT(64) ALIGNED;
    /*
     * If successful, return binary time to point of

     * invocation. Otherwise, return 0 - this results
     * in absolute time 17-NOV-1858.
     */
    STS$VALUE = SYS$BINTIM(ASCII_STRING,BINARY_TIME);  ❷
    IF STS$SUCCESS
    THEN
        RETURN(BINARY_TIME);
    ELSE
        RETURN((64)'0'B);
    END GETBINTIM;

The procedure in Example 11.6, “Setting a Timer” uses the Set Timer (SYS$SETIMR) system service. It issues a time request for some activity to occur in 10 seconds and specifies the number of an event flag to be set when the 10 seconds have elapsed. The following notes are keyed to Example 11.6, “Setting a Timer”:

SET_TIMER: PROCEDURE OPTIONS(MAIN) RETURNS(FIXED BINARY(31));
    %INCLUDE LIB$GET_EF;
    %INCLUDE LIB$FREE_EF;
    %INCLUDE SYS$SETIMR;
    %INCLUDE SYS$WAITFR;
    %INCLUDE $STSDEF;
    DECLARE
        GETBINTIM ENTRY(CHAR(*))  /* character string time */   ❶
            RETURNS(BIT(64) ALIGNED);
    DECLARE EVENT_FLAG_NUM FIXED BIN(31);
    /*
     * Get an event flag to use.
     */
    STS$VALUE = LIB$FREE_EF(EVENT_FLAG_NUM);                     ❷
    IF ^STS$SUCCESS
    THEN RETURN(STS$VALUE);

    /*
     * Set the timer for 10 seconds.
     */
    STS$VALUE = SYS$SETIMR(EVENT_FLAG_NUM,
                    GETBINTIM('0 00:00:10'),,);                 ❸
    IF ^STS$SUCCESS
    THEN RETURN(STS$VALUE);

    /*
     * Wait for the event flag, and display a
     * message when the timer completes.
     */
    STS$VALUE = SYS$WAITFR(EVENT_FLAG_NUM);                     ❹
    IF ^STS$SUCCESS
    THEN RETURN(STS$VALUE);
    PUT SKIP LIST('Timer up!');
    /*
     * Release the event flag.
     */
    STS$VALUE = LIB$GET_EF(EVENT_FLAG_NUM);
    RETURN(STS$VALUE);
    END SET_TIMER;

The following notes are keyed to Example 11.7, “Establishing a Ctrl/c Routine”:

SET_CTRLC: PROCEDURE RETURNS(FIXED BINARY(31));
    %INCLUDE SYS$ASSIGN;                                       ❶
    %INCLUDE SYS$QIO;
    %INCLUDE SYS$WAITFR;
    %INCLUDE $IODEF;                                           ❷
    %INCLUDE $STSDEF;

    DECLARE TTCHAN FIXED BINARY(15);                           ❸

    DECLARE
        1 IOSB,                                                ❹
          2 VALUE FIXED (15),         /* Return status */
          2 NOT_USED(3) FIXED (15),
        C_AST ENTRY(POINTER);    /* CTRL/C AST routine */      ❺

    DECLARE
        CNTRL_C_INTER STATIC BIT(1) ALIGNED GLOBALDEF,         ❻
        IO_SUCCESS BIT(1) ALIGNED BASED(ADDR(IOSB.VALUE));     ❼

    DECLARE VALUE BUILTIN;

    /*
     * Call Assign I/O channel to get a terminal channel and then
     * call Queue I/O Request to enable the terminal for CTRL/C.
     */
    STS$VALUE = SYS$ASSIGN ('TT',TTCHAN,,);                     ❽
    IF ^STS$SUCCESS
    THEN RETURN(STS$VALUE);

    STS$VALUE = SYS$QIO (1,TTCHAN,
                IO$_SETMODE|IO$M_CTRLCAST, /* function */  ❾
                IOSB,                   /* I/O status block */
                ,,                 /* omit QIO AST argument */
                VALUE(C_AST),  /* AST routine for IO$_CTRLCAST */
                ,,,,);           /* unspecified p2 through p6 */
    IF ^STS$SUCCESS
    THEN RETURN(STS$VALUE);

    STS$VALUE = SYS$WAITFR(1);
    IF ^IO_SUCCESS
    THEN RETURN(IOSB.VALUE);                                     ❿

    CNTRL_C_INTER = '0'B;
    RETURN(1);
    END SET_CTRLC;

The following description refers to Example 11.8, “Ctrl/c Handler”.

Once a Ctrl/c handler has executed, it cannot be executed again unless the I/O request that establishes a handler is reexecuted. To keep a Ctrl/c handler active, it is common practice to reenable the Ctrl/c routine within the AST routine itself. The C_AST interrupt routine sets the CNTRL_C_INTER bit. When control is returned to the main routine, a Ctrl/c interrupt message is printed out. In addition, the Ctrl/c handler is reenabled by calling SET_CTRLC.

C_AST: PROCEDURE;
    DECLARE CNTRL_C_INTER STATIC BIT(1) ALIGNED GLOBALREF;
    CNTRL_C_INTER = '1'B;
    END C_AST;

The procedure TESTC, in Example 11.9, “Testing the Ctrl/c Routine”, tests the SET_CTRLC and C_AST routines. The techniques used here can be applied to any procedure in which you want to detect and respond to an external interrupt via Ctrl/c.

TESTC: PROCEDURE OPTIONS(MAIN) RETURNS(FIXED BIN(31));

    /*
     * Field declarations for Return Status Values.
     */
    %INCLUDE $STSDEF;

    DECLARE SET_CTRLC ENTRY RETURNS(FIXED BIN(31));           ❶
    DECLARE CNTRL_C_INTER BIT(1) GLOBALREF;
    %REPLACE TRUE BY '1'B;


    SIGNAL_INTER: PROCEDURE;                                  ❷
        PUT SKIP LIST('Control/C interrupt');
        STS$VALUE = SET_CTRLC();   /* reenable CTRL/C handler */
        END;

    STS$VALUE = SET_CTRLC_();                                 ❸
    IF ^STS$SUCCESS
    THEN
        RETURN(STS$VALUE);

    DO WHILE (TRUE);                                          ❹
        IF CNTRL_C_INTER
        THEN
            CALL SIGNAL_INTER;
        END;

    END TESTC;

The following notes are keyed to Example 11.9, “Testing the Ctrl/c Routine”:

Note that when this program is run, it can be interrupted at the terminal and stopped only by the Ctrl/y function.