 |
OpenVMS Utility Routines Manual
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 Returned1
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.
|
Condition Values Returned1
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 Bit1 |
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.
|
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 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.
|
|
