 |
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
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
User argument. The user_arg argument is passed to the
user-written initialization routine INITIALIZE.
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.
|
TPU$MESSAGE
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.
TPU$PARSEINFO
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.
TPU$SIGNAL
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.
TPU$SPECIFY_ASYNC_ACTION
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.
|
TPU$TPU
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 Returned1
This routine returns any condition value returned by TPU$INITIALIZE,
TPU$EXECUTE_INIFILE, TPU$CONTROL, and TPU$CLEANUP.
TPU$TRIGGER_ASYNC_ACTION
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.
|
FILEIO
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 Returned1
The condition values returned are determined by the user and should
indicate success or failure of the operation.
FILE_PARSE
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.
|
1TPU$M... indicates a mask. There is a corresponding value
for each mask in the form TPU$V....
filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
The object file specification.
default-spec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Contains the default file specification. The value 0 is passed if there
is no default-spec argument.
related-spec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
The related-spec argument contains the related file
specification. The value 0 is passed if there is no 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.
|
