HP OpenVMS Systems Documentation

HP Pascal for OpenVMS
Language Reference Manual

The C_STR function takes a compile-time string expression and returns a C_STR_T pointer to a static string literal with a terminating null character.

 C_STR(e)

The C_STR function can also accept a Pascal variable of either PACKED ARRAY OF CHAR, VARYING OF CHAR, or STRING.

 C_STR(v)

In this form, it will return a C_STR_T value that represents the first character in the string variable. It does not ensure a terminating null byte. The programmer must handle the null-termination to treat a Pascal string variable as a null-terminated string.

8.17 CARD Function

The CARD function returns an integer value indicating the number of components that are currently elements of the set expression.

The parameter s must be a set expression.

For More Information:

• On sets ( Section 2.4.3)

The CHR function returns a char value whose ordinal value in the ASCII character set is the parameter, provided such a character exists.

The parameter x must be integer or unsigned and have a value from 0 to 255.

For More Information:

• On the ASCII character set ( Section 1.2.1)

The CLEAR_INTERLOCKED function assigns the value FALSE to the parameter and returns the original Boolean value of the parameter.

The parameter b must be a variable of type BOOLEAN. The variable does not have to be aligned; therefore, it can be a field of a packed record.

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 CLOCK function returns an integer value indicating the amount of central processor time (in milliseconds) used by the current process. This function does not have a parameter list. The result of CLOCK includes the amount of central processor time allocated to all previously executed images.

8.21 COS Function

The COS function returns a real value that represents the cosine of the specified parameter.

The parameter x can be an integer or REAL type, and is expressed in radians.

8.22 CREATE_DIRECTORY Procedure

The CREATE_DIRECTORY procedure creates a new directory or subdirectory.

The file-name parameter must be a directory name, and optionally can contain a device name. The error-return parameter is optional, and will return an error recovery code if specified.

For More Information:

• On error recovery codes (HP Pascal for OpenVMS User Manual)

The DATE and TIME functions provide a standard way of returning a character-string value that indicates the calendar date and time. The return value is compatible with all string types.

   DATE( t )
   TIME( t )

The parameter t is a variable of the predeclared type TIMESTAMP. You can either call the GETTIMESTAMP procedure to initialize parameter t before you pass t to either DATE or TIME, or you can construct your own TIMESTAMP object.

The size of the function's return value depends on the string length that is normally returned by your system for either date or time data. Consider the following example:

VAR
    Time_Var : TIMESTAMP;
    The_Time, The_Date : STRING( 23 );
{In the executable section:}
GETTIMESTAMP( Time_Var );
The_Date := DATE( Time_Var );
The_Time := TIME( Time_Var );
WRITELN( The_Date, The_Time );  {Writes: 15-JUL-1992 14:20:25.98}

For More Information:

• On the GETTIMESTAMP predeclared procedure ( Section 8.38)
• On the layout of the TIMESTAMP type ( Section 2.8)

The DATE and TIME procedures write the date and the time to their parameters.

   DATE( str )
   TIME( str )

The parameter str must be of type PACKED ARRAY[1..11] OF CHAR. After execution of the procedure, the parameter str contains either the date or the time. If the day of the month is a 1-digit number, the leading zero does not appear in the result; that is, a space appears before the date string. The time is returned in 24-hour format.

For More Information:

• On standard ways to obtain the date and the time ( Section 8.23)

The DBLE function converts the parameter and returns its DOUBLE equivalent.

The parameter x must be of an arithmetic type. The value of x must not be too large to be represented by a double-precision number.

For More Information:

• On precision and support for the DOUBLE data type (Chapter 2)

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

The parameter x is the expression to be converted. The DEC function can take a parameter of any type except VARYING OF CHAR, conformant parameters, or schema types. The DEC function requires the size of x to be less than or equal to the size of INTEGER64 (if supported), or less than or equal to the size of INTEGER32.

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 do not specify values for the optional parameters, a default length and a default minimum number of significant digits is used.

If the size of x is greater than 32, the defaults are 20 characters for the length and 19 characters for the minimum number of digits. Otherwise, the defaults are 11 characters for the length and 10 characters for the minimum number of digits. Because the default length is 1 greater than the number of significant digits, positive numbers will be preceded by a blank and negative numbers will be preceded by a minus sign. Consider the following example.

VAR
   Account : INTEGER;
{In the executable section:}
Account := 16#F;
WRITELN( DEC( Account, 8, 7 ) );

The value of the integer variable Account is converted to its decimal equivalent (15) and, in this example, printed in eight columns: seven digits, and one leading blank ( 0000015).

For More Information:

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

The DELETE_FILE procedure deletes one or more files.

The file-name specification can contain an explicit device and directory name, plus it must contain a file name, a file type or extension, and a version number. If you omit either the directory or device name, HP Pascal uses the directory you are working in at the time of program execution.

The error return parameter returns an error recovery code if specified.

For More Information:

• On error recovery codes (HP Pascal for OpenVMS User Manual)

The DISPOSE procedure deallocates memory for a dynamic variable.

The parameter p is a pointer expression. The t parameters are constant expressions that match the corresponding t parameter used in the call to the NEW procedure that allocated the memory. If you use t parameters in a call to NEW, you must specify the same t parameters in the call to DISPOSE. If you allocated memory using d parameters, just specify the pointer variable to the corresponding DISPOSE call.

The DISPOSE procedure deallocates the object to which the pointer variable points. You cannot call DISPOSE more than once for the same dynamic variable. Consider the following example:

DISPOSE( Ptr );  {Ptr^ is distroyed; Ptr becomes undefined}

For More Information:

• On the pointer data types ( Section 2.3)
• On the NEW procedure ( Section 8.60)

The EQ function returns a Boolean value that specifies if the parameters are equal according to the ASCII values of the strings' characters.

The parameters str1 and str2 must be character-string expressions. If the EQ function detects unequal string lengths, it stops comparison and returns FALSE. Consider the following example:

VAR
   Match : BOOLEAN;
{In the executable section:}
Match := EQ( 'exit   ', 'exit' );   {Returns FALSE; unequal lengths}
Match := EQ( 'exit', 'exit' );      {Returns TRUE}

For More Information:

• On string data types ( Section 2.6)

The ESTABLISH procedure specifies a condition handler that executes if your program generates operating-system events.

The function-identifier parameter must be the name of a function that has the ASYNCHRONOUS attribute and must return an integer value.

For More Information:

• On the ASYNCHRONOUS attribute ( Section 10.2.3)
• On error and report processing (HP Pascal for OpenVMS User Manual)

The EXP function returns a real value that represents the exponent of the specified parameter (it represents e^x).

The parameter x can be an integer or REAL type.

8.32 EXPO Function

The EXPO function returns the integer exponent of the floating-point representation of the parameter.

The parameter x can be of any real type.

For More Information:

• On precision and support for real numbers (Chapter 2)

The FIND_FIRST_BIT_CLEAR function locates the first bit in a Boolean array whose value is 0 and returns an integer value that specifies the index into the array.

The vector parameter is a variable of type PACKED ARRAY OF BOOLEAN with an integer index type. The optional start-index parameter must be an integer expression that indexes the element at the point at which the search starts. The starting index must be greater than or equal to the vector's lower bound, and less than or equal to 1 plus the vector's upper bound; otherwise, a range violation occurs. If omitted, the starting index defaults to the vector's first element.

This function returns a value indexing the first element containing the value 0. If no bit is 0, the result is 1 plus the vector's upper bound. If the vector or the indexed part of the vector has a size of 0, the result is start-index.

8.34 FIND_FIRST_BIT_SET Function

The FIND_FIRST_BIT_SET function locates the first bit in a Boolean array whose value is 1 and returns an integer value that specifies the index into the array.

The vector parameter is a variable of type PACKED ARRAY OF BOOLEAN with an integer index type. The optional start-index parameter must be an expression of an integer type that indexes the element at the point at which the search starts. The starting index must be greater than or equal to the vector's lower bound, and less than or equal to 1 plus the vector's upper bound; otherwise, a range violation occurs. If omitted, the starting index defaults to the vector's first element.

The FIND_FIRST_BIT_SET function returns an integer value indexing the first element containing the value 1. If no bit is 1, the result is 1 plus the vector's upper bound. If the vector or the indexed part of the vector has a size of 0, the result is start-index. Consider the following example:

VAR
   Boo : PACKED ARRAY [0..31] OF BOOLEAN;
{In the executable section:}
Boo::INTEGER := 128;
WRITELN( FIND_FIRST_BIT_SET( BOO ) );

For More Information:

• On the type cast operator (::) ( Section 4.2.6)

The FIND_MEMBER function locates the first character in a string that is a member of a specified set and returns an integer value indicating the position of the character in the string; the function returns 0 if the characters in the string were not members of the set.

The string parameter is a string value, and char-set is a value of type SET OF CHAR.

For More Information:

• On string types ( Section 2.6)
• On sets ( Section 2.4.3)

The FIND_NONMEMBER function locates the first character in a string that is not a member of a specified set and returns an integer value indicating the position of the character in the string; the function returns 0 if the characters in the string were all members of the set.

The string parameter is a string value, and char-set is a value of type SET OF CHAR.

For More Information:

• On string types ( Section 2.6)
• On sets ( Section 2.4.3)

The GE function returns a Boolean value that specifies if the first parameter is greater than or equal to the second parameter, according to the ASCII values of the strings' characters.

The parameters str1 and str2 must be character-string expressions. HP Pascal does not pad shorter strings with blanks. Consider the following example:

VAR
   Match : BOOLEAN;
   Test  : STRING(8) VALUE 'ENTRANCE';
{In the executable section:}
Match := GE( 'exit', 'exit' );   {Returns TRUE}
Match := GE( Test, 'EXIT' );     {'N' less-than 'X': Returns FALSE}

For More Information:

• On string data types ( Section 2.6)

The GETTIMESTAMP procedure initializes its parameter for use with the DATE and TIME functions.

The parameter t is a variable of the TIMESTAMP type, which is a predeclared record type.

The parameter str is a string type that represents a date or both a date and time. The following rules apply to the specification of the str parameter:

• If you do not specify the parameter str, the GETTIMESTAMP procedure initializes the variable to be the date and time at execution of the procedure.
• If you specify an invalid date, the GETTIMESTAMP procedure sets the date to be January 1, 1. If you omit the date, this procedure uses the current date. If you specify an invalid time or if you omit the time, it sets the time to be midnight.

Consider the following example:

VAR
    Time_Var : TIMESTAMP;
    The_Time, The_Date : STRING( 23 );
{In the executable section:}

GETTIMESTAMP( Time_Var );   {Get current date and time}
GETTIMESTAMP( Time_Var, '22-Nov-1988 12:30:15.15');
GETTIMESTAMP( Time_Var, '22-Nov-1988' ); {Midnight at that date}
GETTIMESTAMP( Time_Var, '41-Nov-1988 999:999:999.99' );
{Invalid date; sets TIME_VAR to midnight on January 1, 1}

You can also use predefined values like TOMORROW, as shown in this example:

GETTIMESTAMP( Time_Var, 'TOMORROW' ); {Midnight tomorrow}

For More Information:

• On the DATE and TIME functions ( Section 8.23)
• On the layout of the TIMESTAMP type ( Section 2.8)

The GT function returns a Boolean value that specifies if the first parameter is greater than the second parameter, according to the ASCII values of the strings' characters.

The parameters str1 and str2 must be character-string expressions. HP Pascal does not pad shorter strings with blanks. Consider the following example:

VAR
   Match : BOOLEAN;
   Test  : STRING( 8 ) VALUE 'ENTRANCE';
{In the executable section:}
Match := GT( 'exit', 'exit' );   {Returns FALSE}
Match := GT( Test, 'EXIT' );     {'N' less-than 'X': Returns FALSE}

For More Information:

• On string data types ( Section 2.6)