Updated: 11 December 1998

OpenVMS Utility Routines Manual

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.

user_arg

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.

Description

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.

Condition Values Returned

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.

Format

TPU$MESSAGE string

RETURNS

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.

Argument

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.

Format

TPU$PARSEINFO fileio ,call_user

RETURNS

OpenVMS usage:	item_list
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The routine returns the address of an item list.

Arguments

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.

Description

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.

Format

TPU$SIGNAL condition-code

RETURNS

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.

Argument

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.

Description

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.

Format

TPU$SPECIFY_ASYNC_ACTION facility_index [,tpu_statement]

RETURNS

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.

Argument

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.

Description

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.

Condition Values Returned

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.

Format

TPU$TPU command

RETURNS

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.

Argument

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.

Description

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.

Condition Values Returned

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.

Format

TPU$TRIGGER_ASYNC_ACTION facility_index

RETURNS

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.

Arguments

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.

Description

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.

Condition Values Returned

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).

Format

FILEIO code ,stream ,data

RETURNS

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.

Arguments

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.

Description

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.

Condition Values Returned

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.

Format

FILE_PARSE result-string ,flags ,filespec ,default-spec ,related-spec

RETURNS

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.

Arguments

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.

filespec

default-spec

related-spec

Description

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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4493PRO_015.HTML