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 TPU full callable interface to register asynchronous actions with TPU. 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 TPU 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 TPU 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, TPU 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 TPU after calling TPU$CONTROL. The specified TPU 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 TPU 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. TPU 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 TPU, make sure the application obtains and uses all non-TPU 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 TPU full callable interface to interrupt the TPU 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 TPU statements to execute. 3 Description The TPU$TRIGGER_ASYNC_ACTION routine, along with TPU$SPECIFY_ ASYNC_ACTION routine allow applications to interrupt TPU after calling TPU$CONTROL. The command that was specified for this facility_index is put on the TPU queue of work items and is handled as soon as no other work items are present. This allows TPU to complete and stabilize its environment before executing the command. This routine must be called after control has been passed to TPU 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 TPU file operations. The name of this routine can be either your own file I/O routine or the name of the TPU 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 TPU function. The code argument is the address of a longword containing an item code from TPU, 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 TPU. 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 TPU. 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. TPU 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 TPU built-in procedure FILE_PARSE is called from TPU code, TPU 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. TPU 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 TPU 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 TPU built-in procedure FILE_SEARCH is called from TPU code, TPU 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 VSI 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 VSI 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 VSI 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 TPU 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 TPU. 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 TPU. 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. TPU 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 TPU 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 TPU editor frees this string when necessary. 3 Description This user-written routine is invoked by the TPU 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.