HP OpenVMS Systems Documentation

HP Pascal for OpenVMS
Language Reference Manual

HP Pascal supplies predeclared procedures and functions that perform various commonly used operations. You do not have to declare these routines in order to call them from your code.

In this chapter, the routines are presented in alphabetical order. To save you the time of scrolling through all the routines, you may wish to click on the Table Of Contents entry for the desired routine.

Also in this chapter, the term arithmetic types refers to those data types you can use in arithmetic operations: the integer, unsigned, and real types.

In some sections of this manual, reference is made to entire categories of routines. Table 8-1 lists the routines in each category.

For More Information:

• On data types (Chapter 2)
• On ordinal types ( Section 2.1)
• On pointers ( Section 2.3)
• On arrays and records ( Section 2.4)
• On parameter lists ( Section 6.3)
• On input and output routines ( Section 9.8)
• On data storage (Appendix A)

The ABS function returns a value (of the same data type as the specified parameter) that is the absolute value of the parameter.

The parameter x can be of any arithmetic type.

8.2 ADD_ATOMIC Function (OpenVMS I64 and OpenVMS Alpha systems only)

The ADD_ATOMIC function adds the value of an expression to the value of a variable, stores the newly computed value in the variable, and returns the previous value of the variable.

The type of the expression e must be assignment compatible with that of the variable v. The variable v must be an INTEGER, UNSIGNED, INTEGER64, or UNSIGNED variable and must be allocated on a natural boundary, such as longword for INTEGER and UNSIGNED and quadword for INTEGER64 and UNSIGNED64. The result of ADD_ATOMIC is the same type as the variable v.

Overflow and subrange checking are never performed on the ADD_ATOMIC operation, even if these options are in effect for the rest of the function or compilation unit.

The ADD_ATOMIC function does not provide memory synchronization between multiple processors. The BARRIER predeclared routine must be used for that purpose.

This function is used to access data that is shared between two or more threads of execution.

For More Information

• On atomic operations (HP Pascal for OpenVMS User Manual)

The ADD_INTERLOCKED function adds the value of an expression to the value of a variable, stores the newly computed value in the variable, and returns an integer value: -1 if the new value is negative, 0 if it is zero, and 1 if it is positive.

The type of the expression e must be assignment compatible with that of the variable v. The variable v must be an integer or an unsigned subrange; v must have an allocation size of two bytes and must be aligned on a word boundary. The type of e must be assignment compatible with that of v.

Note that unless the type of v is an integer subrange that includes negative values, the result of the ADD_INTERLOCKED function is never -1.

Overflow and subrange checking are never performed on the ADD_INTERLOCKED operation, even if these options are in effect for the rest of the function or compilation unit.

This function is used to access data that is shared between two or more threads of execution.

For More Information

• On atomic operations (HP Pascal for OpenVMS User Manual)

The ADDRESS function returns a pointer value that is the address of the parameter.

The parameter x can be a variable of any type except a component of a packed structured type. A compile-time warning results if x is a formal VAR parameter, a component of a formal VAR parameter, or a variable that does not have the READONLY or VOLATILE attribute.

A pointer can only refer to a VOLATILE variable or a variable allocated by the NEW procedure.

For More Information:

• Pointer data types ( Section 2.3)
• On the VOLATILE attribute ( Section 10.2.42)
• On the NEW procedure ( Section 8.60)

The AND_ATOMIC function logically ANDs the value of an expression to the value of a variable, stores the newly computed value in the variable, and returns the previous value of the variable.

The type of the expression e must be assignment compatible with that of the variable v. The variable v must be an INTEGER, UNSIGNED, INTEGER64, or UNSIGNED64 variable and must be allocated on a natural boundary, such as longword for INTEGER and UNSIGNED and quadword for INTERGER64 and UNSIGNED64. The result of AND_ATOMIC is the same type as the variable v.

The AND_ATOMIC function does not provide memory synchronization between multiple processors. The BARRIER predeclared routine must be used for that purpose.

This function is used to access data that is shared between two or more threads of execution.

For More Information

• On atomic operations (HP Pascal for OpenVMS User Manual)

The ARCTAN function returns a real value that expresses in radians the arctangent of the specified parameter.

The parameter x can be an integer or REAL type.

8.7 ARGUMENT Function

The ARGUMENT function specifies an argument in a variable-length parameter list that was created using the LIST attribute.

The parameter-name argument specifies the name of a parameter declared with the LIST attribute. The parameter n specifies a positive integer value that identifies the argument. The first argument in a list is always 1. An error occurs if the value supplied for n is less than 1, or exceeds the ARGUMENT_LIST_LENGTH parameter (which indicates the total number of arguments).

If the LIST parameter is a value parameter, ARGUMENT indicates the corresponding value in the argument list. If the LIST parameter is a VAR parameter, ARGUMENT is a reference to the corresponding variable in the argument list.

Also, you can use the IADDRESS function with the ARGUMENT function to return the address of a selected argument.

For More Information:

• On variable-length parameter lists (the example in Section 8.8)
• On parameters ( Section 6.3)
• On the LIST attribute ( Section 10.2.24)
• On the IADDRESS function ( Section 8.42)

The ARGUMENT_LIST_LENGTH function returns an integer value representing the number of arguments in a variable-length parameter list that was created using the LIST attribute.

The parameter-name argument specifies the name of the parameter declared with the LIST attribute.

When creating a variable-length parameter list, you can place the LIST attribute on only the last formal parameter. When you call the routine, you can specify any number of actual parameters, or arguments, that correspond to the last formal parameter declared with LIST. Consider the following example.

PROGRAM Show_Arg( OUTPUT );
                  {Ax corresponds to any number of char. arguments}
PROCEDURE Variable_Write( Fl : VARYING[len] OF CHAR;
                          Ax : [LIST] CHAR );
   VAR
      i : INTEGER;
   BEGIN
   WRITE( Fl, ', ' );
   {For however many arguments there are:}
   FOR i := 1 TO ARGUMENT_LIST_LENGTH( Ax ) DO
      WRITE( ARGUMENT( Ax, i ) );               {Write an argument}
   WRITELN;
   END;
{In the executable section:}
Variable_Write( ' hello', '*' );  {One argument: Writes ' hello, *'}
Variable_Write( ' hello','s','a','i','l','o','r','!' );
                      {Seven arguments: Writes ' hello, sailor!'}

For More Information:

• On parameters ( Section 6.3)
• On the LIST attribute ( Section 10.2.24)

The ASSERT procedure signals a run-time error if the value of its parameter is FALSE. ASSERT takes this form:

The parameter expression is a Boolean expression that is normally true. If ASSERT evaluates the expression as false, it signals a run-time error indicating that the assertion failed.

The optional string parameter is output as part of the error message.

8.10 BARRIER Function (OpenVMS I64 and OpenVMS Alpha systems only)

The BARRIER procedure causes a memory barrier instruction to be emitted to synchronize pending memory updates in a multi-processor environment.

The BARRIER procedure has no parameters.

This routine is used to serialize memory writes on OpenVMS I64 and OpenVMS Alpha systems.

For More Information

• On memory granularity (HP Pascal for OpenVMS User Manual)

The BIN function returns a character-string value that is the binary equivalent of the specified parameter. The return value is compatible with all other string types.

The parameter x is the expression to be converted. This parameter must have a size that is known at compile time; it cannot be VARYING OF CHAR, a conformant parameter, or a schema type.

Two optional integer parameters specify the length of the resulting string and the minimum number of significant digits to be returned. If you specify a length that is too short to hold the converted value, the resulting string is truncated on the left.

If you omit the optional parameters, the bit width of the converted parameter value determines the string length and the number of significant digits. By default, the number of significant digits is the minimum number of characters necessary to express all the bits of the converted parameter. This default length is one character more than the default number of digits, which causes a leading blank to be included in the resulting string when both parameters are omitted. Consider the following example:

TYPE
   Month_Dates = SET OF 0..31;
VAR
   Days_Of_Rain :  Month_Dates;
{In the executable section:}
Days_Of_Rain := [1, 2, 6, 10, 12, 14, 18, 22, 25, 30];
Result := BIN (Days_Of_Rain, 32);
{Returns '01000010010001000101010001000110', 32 characters}

The binary representation is from right to left, with the leftmost bit being bit 31 and the rightmost bit being bit 0.

For More Information:

• On character strings ( Section 2.6)
• On conformant parameters ( Section 6.3.7)

The BIT_OFFSET function returns an integer value that represents the bit position of a field in a record.

The parameter t can be of any record type or variable, and the parameter f can be any field contained in that record.

For More Information:

On records ( Section 2.4.2)

8.13 BITNEXT Function

The BITNEXT function returns an integer value that indicates the number of bits that would be allocated for one component of the specified type in a packed array or if the specified variable appeared as a cell in a packed array.

The parameter x can be a variable or any type identifier.

Cells in a packed array are affected by any alignment attributes placed on them. Therefore, the size returned includes the actual size of the type or variable in addition to trailing space required to ensure proper alignment.

The BITNEXT and BITSIZE functions return the same bit size for a given type or variable, except where the components of the packed array are padded to ensure proper alignment.

For More Information:

• On examples of return values for this function (Table 8-2)
• On packed arrays ( Section 2.4)

The BITSIZE function returns an integer value that indicates the number of bits that would be allocated for one field of the specified type in a packed record or if the specified variable appeared as a field in a packed record.

The parameter x can be a variable or any type identifier.

Fields in a packed record are not affected by any alignment attributes placed on subsequent fields. Therefore, the size returned indicates the actual size of the type or variable.

The BITNEXT and BITSIZE functions return the same bit size for a given type or variable, except where the components of the packed array are padded to ensure proper alignment.

For More Information:

• On possible return values for this function (Table 8-2)
• On packed arrays ( Section 2.4)

The BYTE_OFFSET function returns an integer value that represents the byte position of a field in a record.

The parameter t can be of any record type or variable, and the parameter f can be any field contained in that record.

For More Information:

• On records ( Section 2.4.2)