[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Utility Routines Manual


Previous Contents Index


TPU$FILE_SEARCH

The TPU$FILE_SEARCH routine provides a simplified interface to the $SEARCH system service. DECTPU call this routine when TPU code executes the FILE_SEARCH built-in procedure.

Format

TPU$FILE_SEARCH 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 passed by the flags argument. The memory for the return string is allocated via the Run-Time Library routine LIB$SGET1_DD. To deallocate memory for the string, use the Run-Time Library routine LIB$SFREE1_DD.

flags


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

Determines what file specification components should be returned. The following table lists the valid flag values:
Flag1 Function
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_REPARSE Reparses the file specification before processing. This is intended to be used to reset the file search.
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 will signal the error TPU$_INCKWDCOM and return.
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 will signal the error TPU$_INCKWDCOM and return.

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

Object file specification.

default-spec


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

The default file specification. The default file specification fields are used to fill in the result-string when fields are omitted in the filespec argument. Use the related-spec argument to specify other substitutions.

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 used in the result-string for fields omitted in the filespec and default-spec arguments.

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


Description

This routine allows an application to verify the existence of, and return components of, a file specification. Wildcard operations are permitted. The routine uses the $PARSE and $SEARCH system services to seek the file specification.

If no wildcards are included in the file specification string and the result-string returns a zero (0) length string, no file was found. If wildcard characters were present in the file specification and the result-string returns a zero (0) length string, there are no more files that match the wildcards.

To find all the files that match a wildcard specification, repeatedly call this routine, passing the same arguments, until the routine returns a zero-length result string.

The TPU$FILE_SEARCH routine is called by DECTPU when the TPU built-in procedure FILE_SEARCH 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, the final match operation was detected.
TPU$_INCKWDCOM The flags argument had an illegal combination of values.
TPU$_PARSEFAIL The requested repeat parse failed.
TPU$_SEARCHFAIL An error occurred during the search operation.

TPU$HANDLER

The TPU$HANDLER routine is the DECTPU condition handler.

The DECTPU condition handler invokes the $PUTMSG system service, passing it the address of TPU$MESSAGE.


Format

TPU$HANDLER signal_vector ,mechanism_vector


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

signal_vector


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

Signal vector. See the OpenVMS System Services Reference Manual for information about the signal vector passed to a condition handler.

mechanism_vector


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

Mechanism vector. See the OpenVMS System Services Reference Manual for information about the mechanism vector passed to a condition handler.

Description

The TPU$MESSAGE routine performs the actual output of the message. The $PUTMSG system service only formats the message. It gets the settings for the message flags and facility name from the variables described in Section 8.1.2. Those values can be modified only by the DECTPU built-in procedure SET.

If the condition value received by the handler has a FATAL status or does not have the DECTPU facility code, the condition is resignaled.

If the condition is TPU$_QUITTING, TPU$_EXITING, or TPU$_RECOVERFAIL, a request to UNWIND is made to the establisher of the condition handler.

After handling the message, the condition handler returns with a continue status. DECTPU error message requests are made by signaling a condition to indicate which message should be written out. The arguments in the signal array are a correctly formatted message argument vector. This vector sometimes contains multiple conditions and formatted ASCII output (FAO) arguments for the associated messages. For example, if the editor attempts to open a file that does not exist, the DECTPU message TPU$_NOFILEACCESS is signaled. The FAO argument to this message is a string for the name of the file. This condition has an error status, followed by the OpenVMS RMS status field (STS) and status value field (STV). Because this condition does not have a fatal severity, the editor continues after handling the error.

The editor does not automatically return from TPU$CONTROL. If you call the TPU$CONTROL routine, you must explicitly establish a way to regain control (for example, using the built-in procedure CALL_USER). If you establish your own condition handler but call the DECTPU handler for certain conditions, the default condition handler must be established at the point in your program where you want to return control. You can also interrupt TPU$CONTROL by having your program specify and then trigger an asynchronous routine via the TPU$SPECIFY_ASNYC_ACTION and TPU$TRIGGER_ASYNC_ACTION routines.

See the OpenVMS Calling Standard for details on writing a condition handler.


TPU$INITIALIZE

The TPU$INITIALIZE routine initializes DECTPU for text processing. This routine allocates global data structures, initializes global variables, and calls the appropriate setup routines for each of the major components of the editor, including the Screen Manager and the I/O subsystem.

Format

TPU$INITIALIZE callback [,user_arg]


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

callback


OpenVMS usage: vector_longword_unsigned
type: bound procedure value
access: read only
mechanism: by descriptor

Callback routine. The callback argument is the address of a user-written routine that returns the address of an item list containing initialization parameters or a routine for handling file I/O operations. This callback routine must call a command line parsing routine, which can be TPU$CLIPARSE or a user-written parsing routine.

Callable DECTPU defines item codes that you can use to specify initialization parameters. The following rules must be followed when building the item list:

The following figure shows the general format of an item descriptor. For information about how to build an item list, refer to the programmer's manual associated with the language you are using. Any reference to command line qualifiers refer to those command line qualifiers that you use with the EDIT/TPU command.


The return address in an item descriptor is usually 0.

The following item codes are available:
Item Code Description
TPU$_OPTIONS Enables the command qualifiers. The bits in the bit mask specified by the buffer address field correspond to the various DECTPU command qualifiers.
TPU$_JOURNALFILE Passes the string specified with the /JOURNAL qualifier. The buffer length field is the length of the string, and the buffer address field is the address of the string. This string is available with GET_INFO (COMMAND_LINE,"JOURNAL_FILE"). This string can be a null string.
TPU$_SECTIONFILE Passes the string that is the name of the binary initialization file (section file) to be mapped in. The buffer length field is the length of the string, and the buffer address field is the address of the string. If the TPU$V_SECTION bit is set, this item code must be specified.
TPU$_OUTPUTFILE Passes the string specified with the /OUTPUT qualifier. The buffer length field is the length of the string, and the buffer address field specifies the address of the string. This string is returned by the built-in procedure GET_INFO (COMMAND_LINE, "OUTPUT_FILE"). The string can be a null string.
TPU$_DISPLAYFILE Passes the string specified with the /DISPLAY qualifier. The buffer length field defines the length of the string, and the buffer address field defines the string address. The interface between the TPUSHR image and the display file image is not documented. Applications should only use this option with documented display files such as TPU$CCTSHR or TPU$MOTIFSHR.
TPU$_COMMANDFILE Passes the string specified with the /COMMAND qualifier. The buffer length field is the length of the string, and the buffer address field is the address of the string. This string is returned by the built-in procedure GET_INFO (COMMAND_LINE, "COMMAND_FILE"). The string can be a null string.
TPU$_FILENAME Passes the string that is the name of the first input file specified on the command line. The buffer length field specifies the length of this string, and the buffer address field specifies its address. This string is returned by the built-in procedure GET_INFO (COMMAND_LINE, "FIRST_FILE_NAME"). This file name can be a null string.
TPU$_OTHER_FILENAMES Passes a string that contains the name of an input file that follows the first input file on the command line. The buffer length field specifies the length of this string, and the buffer address field specifies its address. Each additional file specified on the command line requires its own TPU$_OTHER_FILENAMES item entry. These strings are returned by the GET_INFO (COMMAND_LINE,"NEXT_FILE_NAME") built-in procedure in the order they appear in the item list. This item code must appear after the TPU$_FILENAME item in the item list.
TPU$_FILEIO Passes the bound procedure value of a routine to be used for handling file operations. You can provide your own file I/O routine, or you can call TPU$FILEIO, the utility routine provided by DECTPU for handling file operations. The buffer address field specifies the address of a two-longword vector. The first longword of the vector contains the address of the routine. The second longword specifies the environment value that DECTPU loads into R1 before calling the routine.
TPU$_CALLUSER Passes the bound procedure value of the user-written routine that the built-in procedure CALL_USER is to call. The buffer address field specifies the address of a two-longword vector. The first longword of the vector contains the address of the routine. The second longword specifies the environment value that DECTPU loads into R1 before calling the routine.
TPU$_INIT_FILE Passes the string specified with the /INITIALIZATION qualifier. The buffer length field is the length of the string, and the buffer address field is the address of the string. This string is returned by the built-in procedure GET_INFO (COMMAND_LINE,"INIT_FILE").
TPU$_START_LINE Passes the starting line number for the edit. The buffer address field contains the first of the two integer values you specified as part of the /START_POSITION command qualifier. The value is available using the built-in procedure GET_INFO (COMMAND_LINE,"LINE"). Usually an initialization procedure uses this information to set the starting position in the main editing buffer. The first line in the buffer is line 1.
TPU$_START_CHAR Passes the starting column position for the edit. The buffer address field contains the second of the two integer values you specified as part of the /START_POSITION command qualifier. The value is available using the built-in procedure GET_INFO (COMMAND_LINE, "CHARACTER"). Usually an initialization procedure uses this information to set the starting position in the main editing buffer. The first column on a line to character 1.
TPU$_CHARACTERSET Passes the string specified with the /CHARACTER_SET qualifier. The buffer length field specifies the string length and the buffer address field specifies the string address. Valid strings are "DEC_MCS" (the default value), "ISO_LATIN1", and "GENERAL". If the application tries to pass any other string, the routine signals an error and passes the default string (DEC_MCS).
TPU$_WORKFILE Passes the string specified with the /WORK qualifier. The buffer length field specifies the string length and the buffer address specifies the string address. This string is available with GET_INFO (COMMAND_LINE, "WORK_FILE").
TPU$_CHAIN Passes the address of the next item list to the process specified by the buffer address field.
TPU$_ENDLIST Signals the end of the item list.
TPU$_PARENT_WIDGET Passes the appropriate parent widget when invoking the DECwindows version of the editor. This routine is not specified by the application; DECTPU invokes its own application shell. The widget address is passed in the buffer address field. This item code is only valid when using the DECwindows interface.
TPU$_APPLICATION_CONTEXT Passes the application context to use with the TPU$_PARENT_WIDGET. DECTPU defaults to its own application context. The buffer address field specifies the application context address. This item code is only valid when using the DECwindows interface.
TPU$_DEFAULTSFILE Specifies which file DECTPU uses to initialize the X defaults database. The buffer length field specifies the string length and the buffer address field specifies the string address. This item code is only valid when using the DECwindows interface.
TPU$_CTRL_C_ROUTINE Passes the bound procedure value of a routine to be used for handling Ctrl/C asynchronous system traps (ASTs). DECTPU calls the routine when a Ctrl/C AST occurs. If the routine returns a FALSE value, DECTPU assumes that the Ctrl/C has been handled. If the routine returns a TRUE value, DECTPU aborts any currently executing DECTPU procedure. The buffer address field specifies the address of a two-longword vector. The first longword of the vector contains the address of the routine. The second longword specifies the environment value that DECTPU loads into R1 before calling the routine.
TPU$_DEBUGFILE Passes the string specified with the /DEBUG command qualifier. The buffer length field is the length of the string, and the buffer address field is the address of the string.
TPU$_FILE_SEARCH Passes the bound procedure value of a routine to be used to replace the TPU$FILE_SEARCH routine which is called when the built-in procedure FILE_SEARCH is called from TPU code. See the description of the TPU$FILE_SEARCH and the user routine FILE_SEARCH for more information.
TPU$_FILE_PARSE Passes the bound procedure value of a routine to be used to replace the TPU$FILE_PARSE routine which is called when the built-in procedure FILE_PARSE is called from TPU code. See the description of the TPU$FILE_PARSE and the user routine FILE_PARSE for more information.

Table 8-1 lists the bits and corresponding masks enabled by the item code TPU$K_OPTIONS and shows how each bit affects TPU$INITIALIZE operation. Several bits in the TPU$_OPTIONS mask require additional item code entries in the item list. An example of this is TPU$M_COMMAND which requires a TPU$_COMMANDFILE entry in the item list.

Table 8-1 Valid Masks for the TPU$K_OPTIONS Item Code
Mask1 GET_INFO
Request String2
Description
TPU$M_COMMAND COMMAND If DECTPU senses the presence of the TPU$_COMMANDFILE item, it tries to read, compile and execute the unbound TPU code.
TPU$M_COMMAND_DFLTED Not applicable Specifies that DECTPU should use the default command file name of TPU$COMMAND.TPU when reading in the command file. No error is reported if the default command file is not found. TPU$INITIALIZE fails when the TPU$M_COMMAND_DFLTED bit is set to 0 and no file is specified in the item list.
TPU$M_CREATE CREATE The behavior of DECTPU is not affected by this bit. Its interpretation is left to the application layered on DECTPU.
TPU$M_DEBUG Not applicable If DECTPU senses the presence of the TPU$_DEBUGFILE item, it tries to read the file, and then proceeds to compile and execute its contents as TPU statements.
TPU$M_DEFAULTS Not applicable If DECTPU senses the presence of the TPU$_DEFAULTSFILE item, it uses the specified DECwindows X resource file to initialize the DECwindows X resource database.
TPU$M_DISPLAY DISPLAY If DECTPU senses the presence of the TPU$_DISPLAYFILE item, it tries to image activate the specified image as its screen manager. When the bit is 0, DECTPU uses SYS$OUTPUT for display and only the READ_LINE built-in procedure may be used for input.
TPU$M_INIT INITIALIZATION If DECTPU senses the presence of the TPU$_INIT_FILE item, it returns the specified string through the built-in procedure GET_INFO (COMMAND_LINE, "INITIALIZATION_FILE"). Processing of the initialization file is left to the application.
TPU$M_JOURNAL JOURNAL If DECTPU senses the presence of the TPU$_JOURNALFILE item, it outputs the keystrokes entered during the editing session to the specified file.

Note: Compaq recommends the use of buffer change journaling in new applications.

TPU$M_MODIFY MODIFY The behavior of DECTPU is not affected by this bit. Its interpretation is left to the application layered on DECTPU.
TPU$M_NODEFAULTS Not applicable DECTPU initializes the DECwindows X resource database only with resource files that the DECwindows toolkit routine XtApplInitialize loads into the database.
TPU$M_NOMODIFY NOMODIFY The behavior of DECTPU is not affected by this bit. Its interpretation is left to the application layered on DECTPU.
TPU$M_OUTPUT OUTPUT The behavior of DECTPU is not affected by this bit. Its interpretation is left to the application layered on DECTPU.
TPU$M_READ READ_ONLY The behavior of DECTPU is not affected by this bit. Its interpretation is left to the application layered on DECTPU.
TPU$M_RECOVER RECOVER The behavior of DECTPU is not affected by this bit. Its interpretation is left to the application layered on DECTPU.
TPU$M_SECTION SECTION If DECTPU senses the presence of the TPU$_SECTIONFILE item, it tries to read the specified file as a binary initialization file. TPU$INITIALIZE fails if this bit is set to 1 and the TPU$_SECTIONFILE item is not present in the item list.
TPU$M_SEC_LNM_MODE Not applicable If DECTPU senses the presence of the TPU$M_SEC_LNM_MODE item, it looks only at executive mode logical names when attempting to read in a section file.
TPU$M_WORK WORK If DECTPU senses the presence of the TPU$_WORKFILE item, it uses the specifed file for memory management. If no item list entry is present, and this bit is set to 1, a file is created in SYS$LOGIN:.TPU$WORK.
TPU$M_WRITE WRITE The behavior of DECTPU is not affected by this bit. Its interpretation is left to the application layered on DECTPU.


1The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field in which the bit is set. TPU$V_ is a bit number.
2Most bits in the mask have a corresponding GET_INFO (COMMAND_LINE) request string.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4493PRO_014.HTML