|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
The character string routines listed in Table 24-6 give a high-level language program access to the corresponding VAX machine instructions. For a complete description of these instructions, see the VAX Architecture Reference Manual. For each instruction, the VAX Architecture Reference Manual specifies the contents of all the registers after the instruction executes. The corresponding RTL routines do not make the contents of all the registers available to the calling program.
Table 24-6 lists the LIB$ character string routines and their functions.
| Entry Point | Function |
|---|---|
| LIB$LOCC | Locates a character in a string |
| LIB$MATCHC | Returns the relative position of a substring |
| LIB$SCANC | Scans characters |
| LIB$SKPC | Skips characters |
| LIB$SPANC | Spans characters |
| LIB$MOVC3 | Moves characters |
| LIB$MOVC5 | Moves characters and fills |
| LIB$MOVTC | Moves translated characters |
| LIB$MOVTUC | Move translated characters until specified character is found |
The OpenVMS RTL String Manipulation (STR$) Manual describes STR$ string manipulation routines.
This COBOL program uses LIB$LOCC to return the position of a given letter of the alphabet.
IDENTIFICATION DIVISION.
PROGRAM-ID. LIBLOC.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 SEARCH-STRING PIC X(26)
VALUE "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
01 SEARCH-CHAR PIC X.
01 IND-POS PIC 9(9) USAGE IS COMP.
01 DISP-IND PIC 9(9).
ROUTINE DIVISION.
001-MAIN.
MOVE SPACE TO SEARCH-CHAR.
DISPLAY " ".
DISPLAY "ENTER SEARCH CHARACTER: " WITH NO ADVANCING.
ACCEPT SEARCH-CHAR.
CALL "LIB$LOCC"
USING BY DESCRIPTOR SEARCH-CHAR, SEARCH-STRING
GIVING IND-POS.
IF IND-POS = ZERO
DISPLAY
"CHAR ENTERED (" SEARCH-CHAR ") NOT A VALID SEARCH CHAR"
STOP RUN.
MOVE IND-POS TO DISP-IND.
DISPLAY
"SEARCH CHAR (" SEARCH-CHAR ") WAS FOUND IN POSITION "
DISP-IND.
GO TO 001-MAIN.
|
Table 24-7 lists additional routines that you can use.
| Entry Point | Function |
|---|---|
| LIB$CALLG | Calls a routine using an array argument list |
| LIB$CRC | Computes a cyclic redundancy check |
| LIB$CRC_TABLE | Constructs a table for a cyclic redundancy check |
The LIB$CALLG routine gives your program access to the CALLG instruction. This instruction calls a routine using an argument list stored as an array in memory, as opposed to the CALLS instruction, in which the argument list is pushed on the stack.
The LIB$CRC routine allows your high-level language program to use the CRC instruction, which calculates the cyclic redundancy check. This instruction checks the integrity of a data stream by comparing its state at the sending point and the receiving point. Each character in the data stream is used to generate a value based on a polynomial. The values for each character are then added together. This operation is performed at both ends of the data transmission, and the two result values are compared. If the results disagree, then an error occurred during the transmission.
The LIB$CRC_TABLE routine takes a polynomial as its input and builds the table that LIB$CRC uses to calculate the CRC. You must specify the polynomial to be used.
For more details, see the VAX Architecture Reference Manual.
24.4 Processwide Resource Allocation Routines
This section discusses routines that allocate processwide resources to a single operating system process. The processwide resources discussed here are:
The resource allocation routines are provided so that user routines can use the processwide resources without conflicting with one another.
In general, you must use run-time library resource allocation routines when your program needs processwide resources. This allows RTL routines supplied by HP, and user routines that you write to perform together within a process.
If your called routine includes a call to any RTL routine that frees a processwide resource, and that called routine fails to execute normally, the resource will not be freed. Thus, your routine should establish a condition handler that frees the allocated resource before resignaling or unwinding. For information about condition handling, see Chapter 9.
Table 24-8 list routines that perform processwide resource allocation.
| Entry Point | Function |
|---|---|
| LIB$FREE_LUN | Deallocates a specific logical unit number |
| LIB$GET_LUN | Allocates next arbitrary logical unit number |
| LIB$FREE_EF | Frees a local event flag |
| LIB$GET_EF | Allocates a local event flag |
| LIB$RESERVE_EF | Reserves a local event flag |
BASIC and Fortran use a logical unit number (LUN) to define the file or device a program uses to perform input and output. For a routine to be modular, it does not need to know the LUNs being used by other routines that are running at the same time. For this reason, logical units are allocated and deallocated at run time. You can use LIB$GET_LUN and LIB$FREE_LUN to obtain the next available number. This ensures that your BASIC or Fortran routine does not use a logical unit that is already being used by a calling program. Therefore, you should use this routine whenever your program calls or is called by another program that also allocates LUNs. Logical unit numbers 100 to 119 are available to modular routines through these entry points.
To allocate an LUN, call LIB$GET_LUN and use the value returned as the LUN for your I/O statements. If no LUNs are available, an error status is returned and the logical unit is set to -1 . When the program unit exits, it should use LIB$FREE_LUN to free any LUNs that have been allocated by LIB$GET_LUN. If it does not free any LUNs, the available pool of numbers is freed for use.
If your called routine contains a call to LIB$FREE_LUN to free the LUNs
upon exit, and your routine fails to execute normally, the LUNs will
not be freed. For this reason, you should make sure to establish a
condition handler to call LIB$FREE_LUN before resignaling or unwinding.
Otherwise, the allocated LUN is lost until the image exits.
24.4.2 Allocating Event Flag Numbers
The LIB$GET_EF and LIB$FREE_EF routines operate in a similar way to LIB$GET_LUN and LIB$FREE_LUN. They cause local event flags to be allocated and deallocated at run time, so that your routine remains independent of other routines executing in the same process.
Local event flags numbered 32 to 63 are available to your program. These event flags allow routines to communicate and synchronize their operations. If you use a specific event flag in your routine, another routine may attempt to use the same flag, and the flag will no longer function as expected. Therefore, you should call LIB$GET_EF to obtain the next arbitrary event flag and LIB$FREE_EF to return it to the storage pool. You can obtain a specific event flag number by calling LIB$RESERVE_EF. This routine takes as its argument the event flag number to be allocated.
For information about using event flags, see Chapter 3 and
Chapter 6.
24.5 Performance Measurement Routines
The run-time library timing facility consists of four routines to store count and timing information, display the requested information, and deallocate the storage. Table 24-9 lists these routines and their functions.
| Entry Point | Function |
|---|---|
| LIB$INIT_TIMER | Stores the values of the specified times and counts in units of static or heap storage, depending on the value of the routine's argument |
| LIB$SHOW_TIMER | Obtains and formats for output the specified times and counts that are accumulated since the last call to LIB$INIT_TIMER |
| LIB$STAT_TIMER | Obtains one of the times and counts since the last call to LIB$INIT_TIMER and returns it as an unsigned quadword or longword |
| LIB$FREE_TIMER | Frees the storage allocated by LIB$INIT_TIMER |
Using these routines, you can access the following statistics:
The LIB$SHOW_TIMER and LIB$STAT_TIMER routine are relatively simple tools for testing the performance of a new application. To obtain more detailed information, use the system services SYS$GETTIM (Get Time) and SYS$GETJPI (Get Job/Process Information).
The simplest way to use the run-time library routines is to call LIB$INIT_TIMER with no arguments at the beginning of the portion of code to be monitored. This causes the statistics to be placed in OWN storage. To get the statistics from OWN storage, call LIB$SHOW_TIMER (with no arguments) at the end of the portion of code to be monitored.
If you want a particular statistic, you must include a code argument with a call to LIB$SHOW_TIMER or LIB$STAT_TIMER. LIB$SHOW_TIMER returns the specified statistic(s) in formatted form and sends them to SYS$OUTPUT. On each call, LIB$STAT_TIMER returns one statistic to the calling program as an unsigned longword or quadword value.
Table 24-10 shows the code argument in LIB$SHOW_TIMER or LIB$STAT_TIMER.
| Argument Value | Meaning |
LIB$SHOW_TIMER Format | LIB$STAT_TIMER Format |
|---|---|---|---|
| 1 | Elapsed real time | dddd hh:mm:ss.cc | Quadword, in system time format |
| 2 | Elapsed CPU time | hhhh:mm:ss.cc | Longword, in 10-millisecond increments |
| 3 | Number of buffered I/O operations | nnnn | Longword |
| 4 | Number of direct I/O operations | nnnn | Longword |
| 5 | Number of page faults | nnnn | Longword |
When you call LIB$INIT_TIMER, you must use the optional handler argument only if you want to keep several sets of statistics simultaneously. This argument points to a block in heap storage where the statistics are to be stored. You need to call LIB$FREE_TIMER only if you have specified handler in LIB$INIT_TIMER and you want to deallocate all heap storage resources. In most cases, the implicit deallocation when the image exits is sufficient.
The LIB$STAT_TIMER routine returns only one of the five statistics for each call, and it returns that statistic in the form of an unsigned quadword or longword. LIB$SHOW_TIMER returns the virtual address of the stored information, which BASIC cannot directly access. Therefore, a BASIC program must call LIB$STAT_TIMER and format the returned statistics, as the following example demonstrates.
The following BASIC example uses the run-time library performance analysis routines to obtain timing statistics. It then calls the $ASCTIM system service to translate the 64-bit binary value returned by LIB$STAT_TIMER into an ASCII text string.
100 EXTERNAL INTEGER FUNCTION LIB$INIT_TIMER
EXTERNAL INTEGER FUNCTION LIB$STAT_TIMER
EXTERNAL INTEGER FUNCTION LIB$FREE_TIMER
EXTERNAL INTEGER CONSTANT SS$_NORMAL
200 DECLARE LONG COND_VALUE, RANDOM_SLEEP
DECLARE LONG CODE, HANDLE
DECLARE STRING TIME_BUFFER
HANDLE = 0
TIME_BUFFER = SPACE$(50%)
300 MAP (TIMER) LONG ELAPSED_TIME, FILL
MAP (TIMER) LONG CPU_TIME
MAP (TIMER) LONG BUFIO
MAP (TIMER) LONG DIRIO
MAP (TIMER) LONG PAGE_FAULTS
400 PRINT "This program returns information about:"
PRINT "Elapsed time (1)"
PRINT "CPU time (2)"
PRINT "Buffered I/O (3)"
PRINT "Direct I/O (4)"
PRINT "Page faults (5)"
PRINT "Enter zero to exit program"
PRINT "Enter a number from one to"
PRINT "five for performance information"
INPUT "One, two, three, four, or five"; CODE
PRINT
450 GOTO 32766 IF CODE = 0
500 COND_VALUE = LIB$INIT_TIMER( HANDLE )
550 IF (COND_VALUE <> SS$_NORMAL) THEN PRINT @
"Error in initialization"
GOTO 32767
650 A = 0 !
FOR I = 1 to 100000 ! This code merely uses some CPU time
A = A + 1 !
NEXT I !
700 COND_VALUE = LIB$STAT_TIMER( CODE, ELAPSED_TIME, HANDLE )
750 IF (COND_VALUE <> SS$_NORMAL) THEN PRINT @
"Error in statistics routine"
GOTO 32767
800 GOTO 810 IF CODE <> 1%
CALL SYS$ASCTIM ( , TIME_BUFFER, ELAPSED_TIME, 1% BY VALUE)
PRINT "Elapsed time: "; TIME_BUFFER
810 PRINT "CPU time in seconds: "; .01 * CPU_TIME IF CODE = 2%
PRINT "Buffered I/O: ";BUFIO IF CODE = 3%
PRINT "Direct I/O: ";DIRIO IF CODE = 4%
PRINT "Page faults: ";PAGE_FAULTS IF CODE = 5%
PRINT
900 GOTO 400
32765 COND_VALUE = LIB$FREE_TIMER( HANDLE )
32766 IF (COND_VALUE <> SS$_NORMAL) THEN PRINT @
"Error in LIB$FREE_TIMER"
GOTO 32767
32767 END
|
For information about using system time, see Chapter 27.
24.6 Output Formatting Control Routines
Table 24-11 lists the run-time library routines that customize output.
| Entry Point | Function |
|---|---|
| LIB$CURRENCY | Defines the default currency symbol for process |
| LIB$DIGIT_SEP | Defines the default digit separator for process |
| LIB$LP_LINES | Defines the process default size for a printed page |
| LIB$RADIX_POINT | Defines the process default radix point character |
The LIB$CURRENCY, LIB$DIGIT_SEP, LIB$LP_LINES, and LIB$RADIX_POINT routines allow you to customize output. Using them, you can define the logical names SYS$CURRENCY, SYS$DIGIT_SEP, SYS$LP_LINES, and SYS$RADIX_POINT to specify your own currency symbol, digit separator, radix point, or number of lines per printed page. Each routine works by attempting to translate the associated logical name as a process, group, or system logical name. If you have redefined a logical name for a specific local application, then the translation succeeds, and the routine returns the value that corresponds to the option you have chosen. If the translation fails, the routine returns a default value provided by the run-time library, as follows:
| $ | SYS$CURRENCY |
| , | SYS$DIGIT_SEP |
| . | SYS$RADIX_POINT |
| 66 | SYS$LP_LINES |
For example, if you want to use the British pound sign (£) as the currency symbol within your process, but you want to leave the dollar sign ($) as the system default, define SYS$CURRENCY to be in your process logical name table. Then, any calls to LIB$CURRENCY within your process return "£", while any calls outside your process return "$".
You can use LIB$LP_LINES to monitor the current default length of the line printer page. You can also supply your own default length for the current process. United States standard paper size permits 66 lines on each physical page.
If you are writing programs for a utility that formats a listing file to be printed on a line printer, you can use LIB$LP_LINES to make your utility independent of the default page length. Your program can use LIB$LP_LINES to obtain the current length of the page. It can then calculate the number of lines of text per page by subtracting the lines used for margins and headings.
The following is one suggested format:
There are several other RTL routines that permit high-level access to components of the operating system. Table 24-12 lists these routines and their functions. The sections that follow give further details about some of these routines.
| Entry Point | Function |
|---|---|
| LIB$AST_IN_PROG | Indicates whether an asynchronous system trap is in progress |
| LIB$ASN_WTH_MBX | Assigns an I/O channel and associates it with a mailbox |
| LIB$CREATE_DIR | Creates a directory or subdirectory |
| LIB$FIND_IMAGE_SYMBOL | Reads a global symbol from the shareable image file and dynamically activates a shareable image into the P0 address space of a process |
| LIB$ADDX | Performs addition on signed two's complement integers of arbitrary length (multiple-precision addition) |
| LIB$SUBX | Performs subtraction on signed two's complement integers of arbitrary length (multiple-precision subtraction) |
| LIB$FILE_SCAN | Finds file names given OpenVMS RMS file access block (FAB) |
| LIB$FILE_SCAN_END | Specifies end-of-file scan |
| LIB$FIND_FILE | Finds file names given string |
| LIB$FIND_FILE_END | Specifies the end-of-find file |
| LIB$INSERT_TREE | Inserts an element in a binary tree |
| LIB$LOOKUP_TREE | Finds an element in a binary tree |
| LIB$TRAVERSE_TREE | Traverses a binary tree |
| LIB$GET_COMMON | Gets a record from the process's COMMON storage area |
| LIB$PUT_COMMON | Puts a record to the process's COMMON storage area |
An asynchronous system trap (AST) is a mechanism for providing a software interrupt when an external event occurs, such as when a user presses the Ctrl/C key sequence. When an external event occurs, the operating system interrupts the execution of the current process and calls a routine that you supply. While that routine is active, the AST is said to be in progress, and the process is said to be executing at AST level. When your AST routine returns control to the original process, the AST is no longer active and execution continues where it left off.
The LIB$AST_IN_PROG routine indicates to the calling program whether an AST is currently in progress. Your program can call LIB$AST_IN_PROG to determine whether it is executing at AST level, and then take appropriate action. This routine is useful if you are writing AST-reentrant code.
For information about using ASTs, see Chapter 8.
| Previous | Next | Contents | Index |