| Previous | Contents | Index |
To create the bits, start with the value 0, then use the OR operator on the mask (TPU$M...) of each item you want to set. Another way to create the bits is to treat the 32 bits as a bit vector and set the bit (TPU$V...) corresponding to the item you want.
| OpenVMS usage: | user_arg |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
The user_arg parameter is provided to allow an application to pass information through TPU$INITIALIZE to the user-written initialization routine. DECTPU does not interpret this data in any way.
This is the first routine that must be called after establishing a condition handler.This routine initializes the editor according to the information received from the callback routine. The initialization routine defaults all file specifications to the null string and all options to off. However, it does not default the file I/O or call-user routine addresses.
TPU$_SUCCESS Initialization was completed successfully. TPU$_FAILURE General code for all other errors during initialization. TPU$_INSVIRMEM Insufficient virtual memory exists for the editor to initialize. TPU$_NOFILEROUTINE No routine has been established to perform file operations. TPU$_NONANSICRT The input device (SYS$INPUT) is not a supported terminal. TPU$_RESTOREFAIL An error occurred during the restore operation. TPU$_SYSERROR A system service did not work correctly.
The TPU$MESSAGE routine writes error messages and strings using the built-in procedure, MESSAGE.Call this routine to have messages written and handled in a manner consistent with DECTPU. This routine should be used only after TPU$EXECUTE_INIFILE.
TPU$MESSAGE string
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value.
Note
The return status should be ignored because it is intended for use by the $PUTMSG system service.
string
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Formatted message. The string argument is the address of a descriptor of text to be written. It must be completely formatted. This routine does not append the message prefixes. However, the text is appended to the message buffer if one exists. In addition, if the buffer is mapped to a window, the window is updated.
The TPU$PARSEINFO routine parses a command and builds the item list for TPU$INITIALIZE.
TPU$PARSEINFO fileio ,call_user
OpenVMS usage: item_list type: longword (unsigned) access: read only mechanism: by reference
fileio
OpenVMS usage: vector_longword_unsigned type: bound procedure value access: read only mechanism: by descriptor
File I/O routine. The fileio argument is the address for a descriptor of a file I/O routine.call_user
OpenVMS usage: vector_longword_unsigned type: bound procedure value access: read only mechanism: by descriptor
Call-user routine. The call_user argument is the address for a descriptor of a call-user routine.
The TPU$PARSEINFO routine parses a command and builds the item list for TPU$INITIALIZE.This routine uses the command language (CLI) routines to parse the current command. It makes queries about the command parameters and qualifiers that DECTPU expects. The results of these queries are used to set up the proper information in an item list. The addresses of the user routines are used for those items in the list. The address of this list is the return value of the routine.
If your application parses information that is not related to the operation of DECTPU, make sure the application obtains and uses all non-DECTPU parse information before the application calls the TPU$PARSEINFO interface. This is because TPU$PARSEINFO destroys all parse information obtained and stored before TPU$PARSEINFO was called.
The TPU$SIGNAL routine allows applications and user-written TPU routines such as FILEIO to easily signal error messages in order for TPU error handlers to perform correctly.
TPU$SIGNAL condition-code
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. In most cases, the routine returns either the same signal passed to it in the condition value argument, or the return value of LIB$SIGNAL. If the routine fails, it signals TPU$_FAILURE and returns control to the caller.
condition-code
OpenVMS usage: cond_value type: longword (unsigned) access: read only mechanism: by value
The condition-code is an unsigned longword that contains the condition code to be signaled. In most cases, this argument is a TPU message code.
TPU$SIGNAL performs the same function as the Run-Time Library routine LIB$SIGNAL, but it also processes TPU facility messages to allow TPU language ON_ERROR handlers to be called.For example, assume that a user-written file input/output routine is designed to signal the error TPU$_OPENIN when it fails to open a file. Calling the TPU$SIGNAL routine and passing the value TPU$_OPENIN allows a case-style TPU ON_ERROR handler to receive the error, thus preserving the documented return values for TPU built-in procedures such as READ_FILE.
Note
You must call TPU$INITIALIZE before you call the TPU$SIGNAL routine.If TPU$_QUITTING, TPU$_EXITING, or TPU$_RECOVERFAIL are passed to the routine, it calls the Run-Time Library routine LIB$SIGNAL.
If facility messages other than TPU messages are passed to the TPU$SIGNAL routine, it calls the LIB$SIGNAL routine and passes the appropriate condition value.
The TPU$SPECIFY_ASYNC_ACTION routine allows applications using the DECTPU full callable interface to register asynchronous actions with DECTPU.
TPU$SPECIFY_ASYNC_ACTION facility_index [,tpu_statement]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.
facility_index
OpenVMS usage: longword_unsigned type: longword (signed) access: read only mechanism: by reference
Represents an index of the asynchronous action. This index is used with the TPU$TRIGGER_ASYNC_ACTION routine to let DECTPU know what action to perform. It may also be used to delete an action routine (by omitting the tpu_statement). You may register several asynchronous actions depending on your application's needs. This facility index number may be any positive integer.tpu_statement
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
The DECTPU statement you want executed when you call the TPU$TRIGGER_ASYNC_ACTION routine. The statement is compiled and then stored internally. If you omit the parameter, DECTPU removes the action from its list of asynchronous events.
The TPU$SPECIFY_ASYNC_ACTION routine, along with TPU$TRIGGER_ASYNC_ACTION, allow applications to interrupt DECTPU after calling TPU$CONTROL. The specified DECTPU statement is compiled and saved.This routine must be called after TPU$INITIALIZE. It will not complete successfully if keystroke journaling is enabled.
TPU$_SUCCESS Normal successful completion. TPU$_COMPILEFAIL The code specified in tpu_statement did not compile successfully. TPU$_INVPARM An invalid parameter was passed. TPU$_JNLACTIVE Keystroke journaling is active. This routine requires that either journaling be turned off or that buffer change journaling be used.
The TPU$TPU routine invokes DECTPU and is equivalent to the DCL command EDIT/TPU.
TPU$TPU command
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.
command
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Command string. Note that the verb is TPU instead of EDIT/TPU. The command argument is the address for a descriptor of a command line.
This routine takes the command string specified and passes it to the editor. DECTPU uses the information from this command string for initialization purposes, just as though you had entered the command at the DCL level.Using the simplified callable interface does not set TPU$CLOSE_SECTION. This feature lets you make multiple calls to TPU$TPU without requiring you to open and close the section file on each call.
If your application parses information that is not related to the operation of DECTPU, make sure the application obtains and uses all non-DECTPU parse information before the application calls TPU$TPU. This is because TPU$TPU destroys all parse information obtained and stored before TPU$TPU was called.
This routine returns any condition value returned by TPU$INITIALIZE, TPU$EXECUTE_INIFILE, TPU$CONTROL, and TPU$CLEANUP.
The TPU$TRIGGER_ASYNC_ACTION routine allows applications using the DECTPU full callable interface to interrupt the DECTPU TPU$CONTROL loop at an asynchronous level.
TPU$TRIGGER_ASYNC_ACTION facility_index
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.
facility_index
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
The facility_index argument represents the asynchronous action to be taken. This is the same index passed to the TPU$SPECIFY_ASYNC_ACTION routine registering what DECTPU statements to execute.
The TPU$TRIGGER_ASYNC_ACTION routine, along with TPU$SPECIFY_ASYNC_ACTION routine allow applications to interrupt DECTPU after calling TPU$CONTROL. The command that was specified for this facility_index is put on the DECTPU queue of work items and is handled as soon as no other work items are present. This allows DECTPU to complete and stabilize its environment before executing the command. This routine must be called after control has been passed to DECTPU via the TPU$CONTROL routine.
TPU$_SUCCESS Normal successful completion. TPU$_UNKFACILITY The facility_index passed to this routine does not match any facility index passed to TPU$SPECIFY_ASYNC_ACTION.
The user-written FILEIO routine is used to handle DECTPU file operations. The name of this routine can be either your own file I/O routine or the name of the DECTPU file I/O routine (TPU$FILEIO).
FILEIO code ,stream ,data
OpenVMS usage: cond_value type: longword (usigned) access: write only mechanism: by reference
Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.
code
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
Item code specifying a DECTPU function. The code argument is the address of a longword containing an item code from DECTPU, which specifies a function to perform.stream
OpenVMS usage: unspecified type: longword (unsigned) access: modify mechanism: by reference
File description. The stream argument is the address of a data structure containing four longwords. This data structure is used to describe the file to be manipulated.data
OpenVMS usage: item_list_3 type: longword (unsigned) access: modify mechanism: by reference
Stream data. The data argument is either the address of an item list or the address of a descriptor.
Note
The value of this parameter depends on which item code you specify.
The bound procedure value of this routine is specified in the item list built by the callback routine. This routine is called to perform file operations. Instead of using your own file I/O routine, you can call TPU$FILEIO and pass it the parameters for any file operation you do not want to handle. Note, however, that TPU$FILEIO must handle all I/O requests for any file it opens. Also, if it does not open the file, it cannot handle any I/O requests for the file. In other words, you cannot mix the file operations between your own file I/O routine and the one supplied by DECTPU.
The condition values returned are determined by the user and should indicate success or failure of the operation.
This is a user-written routine that can be used in place of the TPU$FILE_PARSE routine.
FILE_PARSE result-string ,flags ,filespec ,default-spec ,related-spec
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. The return value is ignored by DECTPU. User-written FILE_PARSE routines should include calls to the TPU$SIGNAL routine to ensure proper error handling.
result-string
OpenVMS usage: char_string type: character string access: write only mechanism: by descriptor
Return value for the built-in procedure FILE_PARSE. The calling program should fill in this descriptor with a dynamic string allocated by the string routines, such as the Run-Time Library routine LIB$SGET1_DD. DECTPU frees this string when necessary.flags
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
The following table lists the valid flag values used to request file specification components:
Flag1 Function TPU$M_NODE Requests for the node component of the file specification. TPU$M_DEV Requests for the device component of the file specification. TPU$M_DIR Requests for the directory component of the file specification. TPU$M_NAME Requests for the name component of the file specification. TPU$M_TYPE Requests for the type component of the file specification. TPU$M_VER Requests for the version component of the file specification. TPU$M_HEAD Requests for the NODE, DEVICE, and DIRECTORY components of the file specification. TPU$M_TAIL Requests for NAME, TYPE, and VERSION components of the file specification.
| OpenVMS usage: | char_string |
| type: | character string |
| access: | read only |
| mechanism: | by descriptor |
| OpenVMS usage: | char_string |
| type: | character string |
| access: | read only |
| mechanism: | by descriptor |
| OpenVMS usage: | char_string |
| type: | character string |
| access: | read only |
| mechanism: | by descriptor |
This routine allows an application to replace the TPU$FILE_PARSE routine with its own file-parsing routine. The calling program passes the address of the file-parsing routine to TPU$INITIALIZE using the TPU$_FILE_PARSE item code.When the DECTPU built-in procedure FILE_PARSE is called from TPU code, DECTPU calls either the user-written routine (if one was passed to TPU$INITIALIZE) or the TPU$FILE_PARSE routine. The return value of the built-in procedure is the string returned in the result-string argument.
To ensure proper operation of the user's ON_ERROR error handlers, errors should be signaled using the TPU$SIGNAL routine.
| Previous | Next | Contents | Index |