OpenVMS Utility Routines Manual

Updated: 11 December 1998

OpenVMS Utility Routines Manual

Contents

Index

TPU$EDIT

The TPU$EDIT routine builds a command string from its parameters and passes it to the TPU$TPU routine.
TPU$EDIT is another entry point to the DECTPU simplified callable interface.

Format

TPU$EDIT input ,output

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

input

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Input file name. The input argument is the address for a descriptor of a file specification.
output

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Output file name. The output argument is the address for a descriptor of an output file specification. It is used with the /OUTPUT command qualifier.

Description

This routine builds a command string and passes it to TPU$TPU. If the length of the output descriptor is nonzero, then the /OUTPUT qualifier is added to the command string. The /OUTPUT qualifier causes a file to be written to the specified file even if no modifications are made to the input file. If the QUIT built-in procedure is called, it prompts the user as if changes had been made to the buffer. This allows applications to check for the existence of the output file to see if the editing session was terminated, which is consistent with other OpenVMS callable editors.
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$EDIT. Your application must do this because TPU$EDIT destroys all parse information obtained and stored before TPU$EDIT is called.

Condition Values Returned

This routine returns the same values as TPU$TPU.

TPU$EXECUTE_COMMAND

The TPU$EXECUTE_COMMAND routine allows your program to execute DECTPU statements.

Format

TPU$EXECUTE_COMMAND string

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

string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by value

DECTPU statement. The string argument is the address of a descriptor of a character string denoting one or more DECTPU statements.

Description

This routine performs the same function as the built-in procedure EXECUTE described in the DEC Text Processing Utility Reference Manual.

Condition Values Returned

TPU$_SUCCESS Normal successful completion.

TPU$_EXECUTEFAIL Execution aborted. This could be because of execution errors or compilation errors.

TPU$_EXITING EXIT built-in procedure was invoked.

TPU$_QUITTING QUIT built-in procedure was invoked.

TPU$EXECUTE_INIFILE

The TPU$EXECUTE_INIFILE routine allows you to execute a user-written initialization file.
This routine must be executed after the editor is initialized and before any other commands are processed.

Format

TPU$EXECUTE_INIFILE

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

None.

Description

Calling the TPU$EXECUTE_INIFILE routine causes DECTPU to perform the following steps:

The command file is read into a buffer. The default is TPU$COMMAND.TPU. If you specified a file on the command line that cannot be found, an error message is displayed and the routine is aborted.
If you specified the /DEBUG qualifier on the command line, the DEBUG file is read into a buffer. The default is SYS$SHARE:TPU$DEBUG.TPU.
The DEBUG file is compiled and executed (if available).
TPU$INIT_PROCEDURE is executed (if available).
The Command buffer is compiled and executed (if available).
TPU$INIT_POSTPROCEDURE is executed (if available).

Note
If you call this routine after calling TPU$CLEANUP, you must set the flags TPU$_EXECUTEPROCEDURE and TPU$_EXECUTEFILE. Otherwise, the initialization file does not execute.

Condition Values Returned

TPU$_SUCCESS Normal successful completion.

TPU$_COMPILEFAIL The compilation of the initialization file was unsuccessful.

TPU$_EXECUTEFAIL The execution of the statements in the initialization file was unsuccessful.

TPU$_EXITING A result of EXIT. If the default condition handler is being used, the session is terminated.

TPU$_FAILURE General code for all other errors.

TPU$_QUITTING A result of QUIT. If the default condition handler is being used, the session is terminated.

TPU$FILEIO

The TPU$FILEIO routine handles all DECTPU file operations. Your own file I/O routine can call this routine to perform some operations for it. However, the routine that opens the file must perform all operations for that file. For example, if TPU$FILEIO opens the file, it must also close it.

Format

TPU$FILEIO code ,stream ,data

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

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 specifying a function to perform. Following are the item codes that you can specify in the file I/O routine:

TPU$K_OPEN---This item code specifies that the data parameter is the address of an item list. This item list contains the information necessary to open the file. The stream parameter should be filled in with a unique identifying value to be used for all future references to this file. The resultant file name should also be copied with a dynamic string descriptor.
TPU$K_CLOSE---The file specified by the stream argument is to be closed. All memory being used by its structures can be released.
TPU$K_CLOSE_DELETE---The file specified by the stream argument is to be closed and deleted. All memory being used by its structures can be released.
TPU$K_GET---The data parameter is the address of a dynamic string descriptor to be filled with the next record from the file specified by the stream argument. The routine should use the routines provided by the Run-Time Library to copy text into this descriptor. DECTPU frees the memory allocated for the data read when the file I/O routine indicates that the end of the file has been reached.
TPU$K_PUT---The data parameter is the address of a descriptor for the data to be written to the file specified by the stream argument.

stream

OpenVMS usage: unspecified

type: longword (unsigned)

access: modify

mechanism: by reference

File description. The stream argument is the address of a data structure consisting of four longwords. This data structure describes the file to be manipulated.
This data structure is used to refer to all files. It is written to when an open file request is made. All other requests use information in this structure to determine which file is being referenced.
The following figure shows the stream data structure:

The first longword holds a unique identifier for each file. The user-written file I/O routine is restricted to values between 0 and 511. Thus, you can have up to 512 files open simultaneously.

The second longword is divided into three fields. The low word is used to store the allocation quantity, that is, the number of blocks allocated to this file from the FAB (FAB$L_ALQ). This value is used later to calculate the output file size for preallocation of disk space. The low-order byte of the second word is used to store the record attribute byte (FAB$B_RAT) when an existing file is opened. The high-order byte is used to store the record format byte (FAB$B_RFM) when an existing file is opened. The values in the low word and the low-order and high-order bytes of the second word are used for creating the output file in the same format as the input file. These three fields are to be filled in by the routine opening the file.

The last two longwords are used as a descriptor for the resultant or the expanded file name. This name is used later when DECTPU processes EXIT commands. This descriptor is to be filled in with the file name after an open operation. It should be allocated with either the routine LIB$SCOPY_R_DX or the routine LIB$SCOPY_DX from the Run-Time Library. This space is freed by DECTPU when it is no longer needed.

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 meaning of this parameter depends on the item code specified in the code field.

When the TPU$K_OPEN item code is issued, the data parameter is the address of an item list containing information about the open request. The following DECTPU item codes are available for specifying information about the open request:

TPU$K_ACCESS item code lets you specify one of three item codes in the buffer address field, as follows:
- TPU$K_IO
- TPU$K_INPUT
- TPU$K_OUTPUT
TPU$K_FILENAME item code is used for specifying the address of a string to use as the name of the file you are opening. The length field contains the length of this string, and the address field contains the address.
TPU$K_DEFAULTFILE item code is used for assigning a default file name to the file being opened. The buffer length field contains the length, and the buffer address field contains the address of the default file name.
TPU$K_RELATEDFILE item code is used for specifying a related file name for the file being opened. The buffer length field contains the length, and the buffer address field contains the address of a string to use as the related file name.
TPU$K_RECORD_ATTR item code specifies that the buffer address field contains the value for the record attribute byte in the FAB (FAB$B_RAT) used for file creation.
TPU$K_RECORD_FORM item code specifies that the buffer address field contains the value for the record format byte in the FAB (FAB$B_RFM) used for file creation.
TPU$K_MAXIMIZE_VER item code specifies that the version number of the output file should be one higher than the highest existing version number.
TPU$K_FLUSH item code specifies that the file should have every record flushed after it is written.
TPU$K_FILESIZE item code is used for specifying a value to be used as the allocation quantity when creating the file. The value is specified in the buffer address field.

Description

By default, TPU$FILEIO creates variable-length files with carriage-return record attributes (FAB$B_RFM = VAR, FAB$B_RAT = CR). If you pass to it the TPU$K_RECORD_ATTR or TPU$K_RECORD_FORM item, that item is used instead.
The following combinations of formats and attributes are acceptable:

Format Attributes

STM,STMLF,STMCR 0,BLK,CR,BLK+CR

VAR 0,BLK,FTN,CR,BLK+FTN,BLK+CR

All other combinations are converted to VAR format with CR attributes.
This routine always puts values greater than 511 in the first longword of the stream data structure. Because a user-written file I/O routine is restricted to the values 0 through 511, you can easily distinguish the file control blocks (FCB) this routine fills in from the ones you created.

Note
DECTPU uses TPU$FILEIO by default when you use the simplified callable interface. When you use the full callable interface, you must explicitly invoke TPU$FILEIO or provide your own file I/O routine.

Format	Attributes
STM,STMLF,STMCR	0,BLK,CR,BLK+CR
VAR	0,BLK,FTN,CR,BLK+FTN,BLK+CR

Condition Values Returned

The TPU$FILEIO routine returns an OpenVMS RMS status code to DECTPU. The file I/O routine is responsible for signaling all errors if any messages are desired.

TPU$FILE_PARSE

The TPU$FILE_PARSE routine provides a simplified interface to the $PARSE system service. DECTPU calls this routine when the built-in procedure FILE_PARSE is executed from TPU code.

Format

TPU$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. Most utility routines return a condition value in R0. See Condition Values Returned.

Arguments

result-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

Includes the components of the file specification specified by the flags argument. The memory for the return string is allocated via the Run-Time Library routine LIB$SGET1_DD. Use the Run-Time Library routine LIB$SFREE1_DD to deallocate the memory for the return string.
flags

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by reference

Determine what file specification components should be returned. The following table shows the valid values for the flags argument:

Flag Bit¹ Description

TPU$M_NODE Returns the node component of the file specification.

TPU$M_DEV Returns the device component of the file specification.

TPU$M_DIR Returns the directory component of the file specification.

TPU$M_NAME Returns the name component of the file specification.

TPU$M_TYPE Returns the type component of the file specification.

TPU$M_VER Returns the version component of the file specification.

TPU$M_HEAD Returns NODE, DEVICE and DIRECTORY components of the file specification. If the TPU$M_NODE, TPU$M_DEV or TPU$M_DIR bits are set while TPU$M_HEAD is set, the routine signals the error TPU$_INCKWDCOM and returns control to the caller.

TPU$M_TAIL Returns NAME, TYPE and VERSION components of the file specification. If the TPU$M_NAME, TPU$M_TYPE or TPU$M_VER bits are set while TPU$M_TAIL is set, the routine signals the error TPU$_INCKWDCOM and returns control to the caller.

Flag Bit¹	Description
TPU$M_NODE	Returns the node component of the file specification.
TPU$M_DEV	Returns the device component of the file specification.
TPU$M_DIR	Returns the directory component of the file specification.
TPU$M_NAME	Returns the name component of the file specification.
TPU$M_TYPE	Returns the type component of the file specification.
TPU$M_VER	Returns the version component of the file specification.
TPU$M_HEAD	Returns NODE, DEVICE and DIRECTORY components of the file specification. If the TPU$M_NODE, TPU$M_DEV or TPU$M_DIR bits are set while TPU$M_HEAD is set, the routine signals the error TPU$_INCKWDCOM and returns control to the caller.
TPU$M_TAIL	Returns NAME, TYPE and VERSION components of the file specification. If the TPU$M_NAME, TPU$M_TYPE or TPU$M_VER bits are set while TPU$M_TAIL is set, the routine signals the error TPU$_INCKWDCOM and returns control to the caller.

¹TPU$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 default file specification fields are used in the result string as substitutes for fields omitted in the filespec argument. You can also make substitutions in the result string using the related-spec argument.

Use the value 0 when no default-spec is to be applied to the file specification.

related-spec

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Contains the related file specification. The fields in the related file specification are substituted in the result-string if a particular field is missing from both the filespec and default-spec arguments.

Use the value 0 when no default-spec is to be applied to the file specification.

Description

The TPU$FILE_PARSE routine returns a string containing the fields requested of the file specified. The file is not required to exist when the parse is done. The intention of the TPU$FILE_PARSE routine is to construct a valid file specification from the information passed in through the file specification, the default file specification, and the related file specification.
The routine uses the $PARSE system service to return the requested information.
The TPU$FILE_PARSE routine is also called by DECTPU when the TPU built-in procedure FILE_PARSE is executed from TPU code. The return value of the built-in procedure is the string returned in the result-string argument.

Condition Values Returned

TPU$_SUCCESS Normal successful completion. If the return string contains a null-string, then the last match of the search operations has occurred.

TPU$_INCKWDCOM The flags argument had an illegal combination of values.

TPU$_PARSEFAIL The parse failed.

Contents

Index

Legal

 
4493PRO_013.HTML

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

TPU$_SUCCESS	Normal successful completion.
TPU$_EXECUTEFAIL	Execution aborted. This could be because of execution errors or compilation errors.
TPU$_EXITING	EXIT built-in procedure was invoked.
TPU$_QUITTING	QUIT built-in procedure was invoked.

TPU$_SUCCESS	Normal successful completion.
TPU$_COMPILEFAIL	The compilation of the initialization file was unsuccessful.
TPU$_EXECUTEFAIL	The execution of the statements in the initialization file was unsuccessful.
TPU$_EXITING	A result of EXIT. If the default condition handler is being used, the session is terminated.
TPU$_FAILURE	General code for all other errors.
TPU$_QUITTING	A result of QUIT. If the default condition handler is being used, the session is terminated.

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

OpenVMS usage:	unspecified
type:	longword (unsigned)
access:	modify
mechanism:	by reference

TPU$_SUCCESS	Normal successful completion. If the return string contains a null-string, then the last match of the search operations has occurred.
TPU$_INCKWDCOM	The flags argument had an illegal combination of values.
TPU$_PARSEFAIL	The parse failed.