HELPLIB.HLB  —  DECTPU  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]

1  –  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.

2  –  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.

4  –  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.
Close Help