1 DECTPU These routines are part of the callable DEC Text Processing Utility (DECTPU). 2 TPU$CLEANUP The TPU$CLEANUP routine cleans up internal data structures, frees memory, and restores terminals to their initial state. This is the final routine called in each interaction with DECTPU. Format TPU$CLEANUP flags 3 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. The condition value that this routine can return is listed under Condition Value Returned. 3 Argument flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Flags (or mask) defining the cleanup options. The flags argument is the address of a longword bit mask defining the cleanup options or the address of a 32-bit mask defining the cleanup options. This mask is the logical OR of the flag bits you want to set. Following are the various cleanup options: Flag(1) Function TPU$M_DELETE_ Closes and deletes the journal file if it is JOURNAL open. TPU$M_DELETE_EXITH Deletes the DECTPU exit handler. TPU$M_DELETE_ Deletes all text buffers. If this is not the BUFFERS last time you are calling DECTPU, then all variables referring to these data structures are reset, as if by the built-in procedure DELETE. If a buffer is deleted, then all ranges and markers within that buffer, and any subprocesses using that buffer, are also deleted. TPU$M_DELETE_ Deletes all windows. If this is not the WINDOWS last time you are calling DECTPU, then all variables referring to these data structures are reset, as if by the built-in procedure DELETE. TPU$M_DELETE_CACHE Deletes the virtual file manager's data structures and caches. If this deletion is requested, then all buffers are also deleted. If the cache is deleted, the initialization routine has to reinitialize the virtual file manager the next time it is called. TPU$M_PRUNE_CACHE Frees up any virtual file manager caches that have no pages allocated to buffers. This frees up any caches that may have been created during the session but are no longer needed. TPU$M_EXECUTE_FILE Reexecutes the command file if TPU$EXECUTE_ INIFILE is called again. You must set this bit if you plan to specify a new file name for the command file. This option is used in conjunction with the option bit passed to TPU$INITIALIZE indicating the presence of the /COMMAND qualifier. TPU$M_EXECUTE_PROC Looks up TPU$INIT_PROCEDURE and executes it the next time TPU$EXECUTE_INIFILE is called. TPU$M_DELETE_ Deletes the entire context of DECTPU. If CONTEXT this option is specified, then all other options are implied, except for executing the initialization file and initialization procedure. TPU$M_RESET_ Resets the terminal to the state it was in TERMINAL upon entry to DECTPU. The terminal mailbox and all windows are deleted. If the terminal is reset, then it is reinitialized the next time TPU$INITIALIZE is called. TPU$M_KILL_ Deletes all subprocesses created during the PROCESSES session. TPU$M_CLOSE_ Closes the section file and releases the SECTION(2) associated memory. All buffers, windows, and processes are deleted. The cache is purged and the flags are set for reexecution of the initialization file and initialization procedure. If the section is closed and if the option bit indicates the presence of the SECTION qualifier, then the next call to TPU$INITIALIZE attempts a new restore operation. TPU$M_DELETE_ Deletes all miscellaneous preallocated data OTHERS structures. Memory for these data structures is reallocated the next time TPU$INITIALIZE is called. TPU$M_LAST_TIME This bit should be set only when you are calling DECTPU for the last time. Note that if you set this bit and then recall DECTPU, the results are unpredictable. Footnotes: 1. The flag 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. 2. Using the simplified callable interface does not set TPU$_ CLOSE_SECTION. This feature allows you to make multiple calls to TPU$TPU without requiring you to open and close the section file on each call. 3 Description The cleanup routine is the final routine called in each interaction with DECTPU. It tells DECTPU to clean up its internal data structures and prepare for additional invocations. You can control what is reset by this routine by setting or clearing the flags described previously. When you finish with DECTPU, call this routine to free the memory and restore the characteristics of the terminal to their original settings. If you intend to exit after calling TPU$CLEANUP, do not delete the data structures; the operating system does this automatically. Allowing the operating system to delete the structures improves the performance of your program. Notes 1. When you use the simplified interface, DECTPU automatically sets the following flags: o TPU$V_RESET_TERMINAL o TPU$V_DELETE_BUFFERS o TPU$V_DELETE_JOURNAL o TPU$V_DELETE_WINDOWS o TPU$V_DELETE_EXITH o TPU$V_EXECUTE_PROC o TPU$V_EXECUTE_FILE o TPU$V_PRUNE_CACHE o TPU$V_KILL_PROCESSES 2. If this routine does not return a success status, no other calls to the editor should be made. 3 Condition_Value_Returned TPU$_SUCCESS Normal successful completion. 2 TPU$CLIPARSE The TPU$CLIPARSE routine parses a command line and builds the item list for TPU$INITIALIZE. Format TPU$CLIPARSE string ,fileio ,call_user 3 Returns OpenVMS usage:item_list type: longword (unsigned) access: read only mechanism: by reference This routine returns the address of an item list. 3 Arguments string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Command line. The string argument is the address of a descriptor of a DECTPU command. 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 of 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 of a descriptor of a call-user routine. 3 Description This routine calls CLI$DCL_PARSE to establish a command table and a command to parse. It then calls TPU$PARSEINFO to build an item list for TPU$INITIALIZE. 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$CLIPARSE. You must do this because TPU$CLIPARSE destroys all parse information obtained and stored before TPU$CLIPARSE was called. 2 TPU$CLOSE_TERMINAL The TPU$CLOSE_TERMINAL routine closes the DECTPU channel to the terminal. Format TPU$CLOSE_TERMINAL 3 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. The condition value that this routine can return is listed under Condition Value Returned. 3 Arguments None. 3 Description This routine is used with the built-in procedure CALL_USER and its associated call-user routine to control the DECTPU access to the terminal. When a call-user routine invokes TPU$CLOSE_ TERMINAL, DECTPU closes its channel to the terminal and the channel of the DECTPU associated mailbox. When the call-user routine returns control to it, DECTPU automatically reopens a channel to the terminal and redisplays the visible windows. A call-user routine can use TPU$CLOSE_TERMINAL at any point in the program and as many times as necessary. If the terminal is already closed to DECTPU when TPU$CLOSE_TERMINAL is used, the call is ignored. 3 Condition_Value_Returned TPU$_SUCCESS Normal successful completion. 2 TPU$CONTROL The TPU$CONTROL routine is the main processing routine of the DECTPU editor. It is responsible for reading the text and commands and executing them. When you call this routine (after calling TPU$INITIALIZE), control is turned over to DECTPU. Format TPU$CONTROL [integer] 3 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. 3 Argument integer OpenVMS usage:integer type: longword (unsigned) access: read only mechanism: by reference Prevents DECTPU from displaying the message "Editing session is not being journaled" when the calling program gives control to DECTPU. Specify a true (odd) integer to preserve compatibility in future releases. If you omit the parameter, DECTPU displays the message if journaling is not enabled. 3 Description This routine controls the editing session. It is responsible for reading the text and commands and for executing them. Windows on the screen are updated to reflect the edits made. Your program can regain control by interrupting DECTPU using the TPU$SPECIFY_ ASYNC_ACTION routine, together with the TPU$TRIGGER_ASYNC_ACTION routine. NOTE Control is also returned to your program if an error occurs or when you enter either the built-in procedure QUIT or the built-in procedure EXIT. 3 Condition_Values_Returned TPU$_EXITING A result of EXIT (when the default condition handler is established). TPU$_NONANSICRT A result of operation termination - results when you call DECTPU with TPU$DISPLAYFILE set to nodisplay and you attempt to execute screen-oriented commands. TPU$_QUITTING A result of QUIT (when the default condition handler is established). TPU$_RECOVERFAIL A recovery operation was terminated abnormally. 2 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 3 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. 3 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. 3 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. 3 Condition_Values_Returned This routine returns the same values as TPU$TPU. 2 TPU$EXECUTE_COMMAND The TPU$EXECUTE_COMMAND routine allows your program to execute DECTPU statements. Format TPU$EXECUTE_COMMAND string 3 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. 3 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. 3 Description This routine performs the same function as the built-in procedure EXECUTE described in the DEC Text Processing Utility Reference Manual. 3 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. 2 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 3 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. 3 Arguments None. 3 Description Calling the TPU$EXECUTE_INIFILE routine causes DECTPU to perform the following steps: 1. 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. 2. 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. 3. The DEBUG file is compiled and executed (if available). 4. TPU$INIT_PROCEDURE is executed (if available). 5. The Command buffer is compiled and executed (if available). 6. 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. 3 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. 2 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 3 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. 3 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: o 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. o TPU$K_CLOSE-The file specified by the stream argument is to be closed. All memory being used by its structures can be released. o 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. o 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. o 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: ---------------------------------------------- | File identifier | ---------------------------------------------- | RFM | | Allocation | ---------------------------------------------- | Class | Type | Length | ---------------------------------------------- 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: o 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 o 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. o 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. o 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. o 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. o 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. o 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. o TPU$K_FLUSH item code specifies that the file should have every record flushed after it is written. o 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. 3 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. 3 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. 2 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 3 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. 3 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(1) 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. (1) 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. 3 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. 3 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. 2 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 3 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. 3 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: Flag(1) 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. (1) 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 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. 3 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. 3 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. 2 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 3 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. 3 Arguments signal_vector OpenVMS usage:arg_list type: longword (unsigned) access: modify mechanism: by reference Signal vector. See the HP 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 HP OpenVMS System Services Reference Manual for information about the mechanism vector passed to a condition handler. 3 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 the OpenVMS Utility Routines Manual in the section about the DECTPU Shareable Image. 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 HP OpenVMS Calling Standard for details on writing a condition handler. 2 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] 3 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. 3 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: o If you use the TPU$_OTHER_FILENAMES item code, it must follow the TPU$_FILENAME item code. o If you use either the TPU$_CHAIN item code or the TPU$_ENDLIST code, it must be the last item code in the 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. --------------------------------------------- | Item code | Buffer length | --------------------------------------------- | Buffer address | --------------------------------------------- | Return address | --------------------------------------------- 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_ Passes a string that contains the name of an FILENAMES 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$_ Passes the string specified with the CHARACTERSET /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_ Passes the appropriate parent widget when WIDGET 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$_ Passes the application context to use with the APPLICATION_ TPU$_PARENT_WIDGET. DECTPU defaults to its own CONTEXT application context. The buffer address field specifies the application context address. This item code is only valid when using the DECwindows interface. TPU$_ Specifies which file DECTPU uses to initialize DEFAULTSFILE 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_ Passes the bound procedure value of a routine 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. Valid Masks for the TPU$K_OPTIONS Item Code 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 6-1 Valid Masks for the TPU$K_OPTIONS Item Code GET_INFO Request Mask(1) String(2) Description TPU$M_ COMMAND If DECTPU senses the presence of COMMAND the TPU$_COMMANDFILE item, it tries to read, compile and execute the unbound TPU code. TPU$M_ Not Specifies that DECTPU should use COMMAND_ applicable the default command file name of DFLTED 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 If DECTPU senses the presence of applicable the TPU$_DEBUGFILE item, it tries to read the file, and then proceeds to compile and execute its contents as TPU statements. TPU$M_ Not If DECTPU senses the presence of DEFAULTS applicable the TPU$_DEFAULTSFILE item, it uses the specified DECwindows X resource file to initialize the DECwindows X resource database. TPU$M_ DISPLAY If DECTPU senses the presence of the DISPLAY 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 INITIALIZATIONIf 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 If DECTPU senses the presence of the JOURNAL TPU$_JOURNALFILE item, it outputs the keystrokes entered during the editing session to the specified file. Note: HP 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_ Not DECTPU initializes the DECwindows X NODEFAULTS applicable resource database only with resource files that the DECwindows toolkit routine XtApplInitialize loads into the database. TPU$M_ NOMODIFY The behavior of DECTPU is not NOMODIFY 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 The behavior of DECTPU is not RECOVER affected by this bit. Its interpretation is left to the application layered on DECTPU. TPU$M_ SECTION If DECTPU senses the presence of the SECTION 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_ Not If DECTPU senses the presence of the LNM_MODE applicable 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. Footnotes: 1. The flag 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. 2. Most bits in the mask have a corresponding GET_INFO (COMMAND_ LINE) request string. 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. 3 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. 3 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$_ No routine has been established to perform NOFILEROUTINE 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. 2 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 3 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. 3 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. 2 TPU$PARSEINFO The TPU$PARSEINFO routine parses a command and builds the item list for TPU$INITIALIZE. Format TPU$PARSEINFO fileio ,call_user 3 Returns OpenVMS usage:item_list type: longword (unsigned) access: read only mechanism: by reference The routine returns the address of an item list. 3 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. 3 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. 2 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 3 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. 3 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. 3 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. 2 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] 3 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. 3 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. 3 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. 3 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. 2 TPU$TPU The TPU$TPU routine invokes DECTPU and is equivalent to the DCL command EDIT/TPU. Format TPU$TPU command 3 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. 3 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. 3 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. 3 Condition_Values_Returned This routine returns any condition value returned by TPU$INITIALIZE, TPU$EXECUTE_INIFILE, TPU$CONTROL, and TPU$CLEANUP. 2 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 3 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. 3 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. 3 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. 3 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. 2 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 3 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. 3 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. 3 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. 3 Condition_Values_Returned The condition values returned are determined by the user and should indicate success or failure of the operation. 2 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 3 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. 3 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: Flag(1) 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. (1) 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 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. 3 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. 2 FILE_SEARCH This is a user-written routine that is used in place of the TPU$FILE_SEARCH routine. Format FILE_SEARCH result-string ,flags ,filespec ,default-spec ,related-spec 3 Returns OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. If an odd numeric value is returned, the next call to the built-in procedure FILE_SEARCH automatically sets the TPU$M_REPARSE bit in the flags longword. TPU$M_REPARSE is also set if the result-string has a length of 0. 3 Arguments result-string OpenVMS usage: char_string type: character string access: write only mechanism: by descriptor Return value for the built-in procedure FILE_SEARCH. Your 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. The TPU$M_REPARSE bit is set in the flags longword if the result- string has a length of zero. The bit is intended to reset the file search when wildcard searches are performed. flags OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The following table shows the flags used for specifying the file components: Flag(1) 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_REPARSE Reparses the file specification before processing. This is intended as a way to restart the file search. This flag will automatically be set by DECTPU if on a previous call to the FILE_SEARCH user routine the result-string has a zero length or the routine returns a odd (noneven) status. TPU$M_HEAD Requests for the NODE, DEVICE, and DIRECTORY components of the file specification. TPU$M_TAIL Requests for the NAME, TYPE, and VERSION component of the file specification. (1) 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 The default-spec argument contains the default file specification. The value 0 is passed if there is no default-spec. 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. 3 Description The FILE_SEARCH user routine allows an application to replace the TPU$FILE_SEARCH routine with its own file-searching routine. The calling program passes the address of the routine to the TPU$INITIALIZE routine using the TPU$_FILE_SEARCH item code. When the DECTPU built-in procedure FILE_SEARCH is called from TPU code, DECTPU calls either the user-written FILE_SEARCH routine (if one was passed to TPU$INITIALIZE) or the TPU$FILE_SEARCH 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 handlers, errors in the user-written FILE_PARSE routine should be signaled using the TPU$SIGNAL routine. 2 HANDLER The user-written HANDLER routine performs condition handling. Format HANDLER signal_vector ,mechanism_vector 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. 3 Arguments signal_vector OpenVMS usage:arg_list type: longword (unsigned) access: modify mechanism: by reference Signal vector. See the HP 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 HP OpenVMS System Services Reference Manual for information about the mechanism vector passed to a condition handler. 3 Description If you need more information about writing condition handlers and programming concepts, refer to HP OpenVMS Programming Concepts Manual. Instead of writing your own condition handler, you can use the default condition handler, TPU$HANDLER. If you want to write your own routine, you must call TPU$HANDLER with the same parameters that your routine received to handle DECTPU internal signals. 2 INITIALIZE The user-written initialization callback routine is passed to TPU$INITIALIZE as a bound procedure value and called to supply information needed to initialize DECTPU. Format INITIALIZE [user_arg] 3 Returns OpenVMS usage:item_list type: longword (unsigned) access: read only mechanism: by reference This routine returns the address of an item list. 3 Arguments user_arg OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value User argument. 3 Description The user-written initialization callback routine is passed to TPU$INITIALIZE as a bound procedure value and called to supply information needed to initialize DECTPU. If the user_arg parameter was specified in the call to TPU$INITIALIZE, the initialization callback routine is called with only that parameter. If user_arg was not specified in the call to TPU$INITIALIZE, the initialization callback routine is called with no parameters. 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. The user-written callback routine is expected to return the address of an item list containing initialization parameters. Because the item list is used outside the scope of the initialization callback routine, it should be allocated in static memory. The item list entries are discussed in the TPU$INITIALIZE help topic. Most of the initialization parameters have a default value; strings default to the null string, and flags default to false. The only required initialization parameter is the address of a routine for file I/O. If an entry for the file I/O routine address is not present in the item list, TPU$INITIALIZE returns with a failure status. 2 USER The user-written USER routine allows your program to take control during a DECTPU editing session (for example, to leave the editor temporarily and perform a calculation). Format USER integer ,stringin ,stringout 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. 3 Arguments integer OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference First parameter to the built-in procedure CALL_USER. This is an input-only parameter and must not be modified. stringin OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Second parameter to the built-in procedure CALL_USER. This is an input-only parameter and must not be modified. stringout OpenVMS usage:char_string type: character string access: modify mechanism: by descriptor Return value for the built-in procedure CALL_USER. Your program should fill in this descriptor with a dynamic string allocated by the string routines (such as LIB$SGET1_DD) provided by the Run- Time Library. The DECTPU editor frees this string when necessary. 3 Description This user-written routine is invoked by the DECTPU built-in procedure CALL_USER. The built-in procedure CALL_USER passes three parameters to this routine. These parameters are then passed to the appropriate part of your application to be used as specified. (For example, they can be used as operands in a calculation within a Fortran program.) Using the string routines provided by the Run-Time Library, your application fills in the stringout parameter in the call-user routine, which returns the stringout value to the built-in procedure CALL_USER. The description of the built-in procedure CALL_USER in the DEC Text Processing Utility Reference Manual shows an example of a BASIC program that is a call-user routine.