Docstoc

114

Document Sample
114 Powered By Docstoc
					              HOLIDAYs
Purpose:

              To mark specified days of the year as holidays (non-working days) at a particular site.
              The HOLIDAYs command is usually used with BASIS time functions.

Syntax:

              HOLIDAYs {FILE= | FD=} fd | ymd {,ymd} 0:199
                    {,WEEKEND_holidays=NO | YES}

Parameters:

              fd                                                                                  (Required)

              Specifies the name of a file that contains the holiday dates, which are stored in
              YYYYMMDD format, with one holiday per record.

              ymd                                                                                 (Optional)

              Specifies the holiday dates, written as numeric constants in YYYYMMDD format.

              WEEKEND_holidays=NO | YES                                                           (Optional)

              Indicates whether weekend holidays are included in the list of holidays that is built as a
              result of this command. The default is NO.


              NO           Weekend holidays are not included.

              YES          Weekend holidays are included.


Prompts:

              None.




                                                                             Command References  327
Key Point:
                   Since the number and dates of holidays vary from one site to another, the BASIS
                    system does not supply a standard set of holidays. The HOLIDAYs command
                    specifies the holiday dates for an individual site. You can store these dates in a file
                    that the HOLIDAYs command accesses, or you can supply them with the
                    HOLIDAYs command.

Examples:
               1.   This proc segment specifies the dates of company holidays with the HOLIDAYs
                    command, making those dates available to the BASIS time functions. The
                    $WORKDAYS function accepts a start date and an end date, and calculates the
                    number of working days (days that are not on weekends or holidays) within the given
                    time span.

                    Proc Segment:
                    HOLIDAYS +
                    19860101,19860526,19860704,19861127,19861128,19861225,19861226
                    *
                    SET/PV PROJ = $WORKDAYS(19861101,19861231)
                    *
                    TELL 'THERE ARE !PROJ! WORKDAYS LEFT TO COMPLETE THE PROJECT.'

                    The dates of holidays can be specified within the HOLIDAYs command. The
                    HOLIDAYs command makes the dates available to the $WORKDAYS function,
                    which calculates the number of working days between a start date and an end date.
               2.   This example shows how you can use an input file to supply dates to the HOLIDAYs
                    command.

                    The OURHOLIDAYs file looks like this:

                    19860101
                    19860120
                    19860217
                    19860526
                    19860704
                    19860901
                    19861127
                    19861128
                    19861225
                    19861226




328  Command References
    Proc Segment:
    HOLIDAYS FD='OURHOLIDAYS'
                                           1
    INQUIRE/PV HOL,'ENTER THE DATE HERE>'
    *
                                 2
    SET/PV HOL = $CONV_DATE(HOL)
                                               3
    SET/PV DAYBEFORE = $WORKDAYS_BEFORE(HOL)
                                             4
    SET/PV DAYAFTER = $WORKDAYS_AFTER(HOL)
    *
    TELL 'THE COMPUTER CENTER IS CLOSING AT 5:00 P.M. ON +
         !DAYBEFORE!.'
    TELL 'NORMAL OPERATIONS RESUME AT 8:00 A.M. ON +
         !DAYAFTER!.'

    1
        The variable HOL stores a date from the OURHOLIDAYs file.
    2
      The $CONV_DATE converts the date from a character string to YYYYMMDD
format, so the $WORKDAYS_BEFORE and $WORKDAYS_AFTER functions can be
used.
    3
      The $WORKDAYS_BEFORE function returns the last working day before the
holiday.
    4
      The $WORKDAYS_AFTER function returns the first working day after the
holiday.




                                                         Command References  329
               IMPort/PLibrary
               UNIX, VMS

Purpose

               To import proc(s) from a source file to a library.

               IMPORTANT: The IMPORT/PLIBRARY command is not applicable to Windows.

Syntax:

               IMPort/PLibrary {=any_pri_lib} {wild_proc_name}
                       {,AUTHOR=author}
                       {,MARKER=proc_marker}
                       {,SOURCE=fd}

Parameters:

               any_priv_lib                                                                        (Optional)

               Specifies the name of the library which will contain the proc(s). This may be the name of
               a specific library or $PRIvate of the private library set. The default is $PRIvate.

               wild_proc_name                                                                      (Optional)

               Specifies the name of the proc(s) to be imported. This name may include wildcards. The
               valid wildcard options are: *proc_name, proc_name*, proc*_name, *proc_name, and *.
               The default is *.

               AUTHOR=author                                                                       (Optional)

               Specifies the author of the imported proc(s). The default is the current value of
               DM_UID.

               MARKER=proc_marker                                                                  (Optional)

               Specifies the character string that delimits and names the entries in the source file. The
               default is *PROC.




330  Command References
              SOURCE=fd                                                                            (Optional)

              Specifies the name of the source file which contains the proc(s). The following is the
              default file name:



                  Operating system         Default source file name

                  NT                       not applicable

                  UNIX                     proc.src

                  VMS                      PROC.SRC;0


              For more information, see BASIS Reference, “Op. Sys. System Specifics” where Op. Sys.
              is the name of your operating system.

Prompts:

              None.

Key Points:
                   This command cannot be used to import a proc into a public library set.
                   The proc-name may include wildcards. The valid wildcard options are: *proc_name,
                    proc_name*, proc*_name*, and *.
                   The source file must contain at least one proc_marker for this command to be
                    successful.
                   If you do not specify a library file, a private library set must be defined.

Example:

              Import a proc from a source file to a library.
                    FQM> IMP/PL=MENU_LIBRARY HELP SOURCE=HELP_MENU
                    1 library entry(s) imported.
                    FQM> SHOW/PL=MENU_LIBRARY/DIR*, HEADER=NO

                    HELP                                                 INTRO_SCREEN
                    MAIN




                                                                                Command References  331
               IMPort/View                                                          (FQM only)
Purpose:

               To import a view record from a file to the database or queue area.

Syntax:

               IMPort {/View} view_ref | view_id
                       {,COMMAND=PUT | ADD | REPLACE | MERGE | CHANGE |
                                                1
                         SAVE | KEEP_save}
                       {,CONVerter=converter}
                       {,DATA_file=fd} | {,FINal_file=fd {,REV_file_type=rev_ftype}}
                       {,ERR=errlabel}
                                                                          1
                       {,NEXT_section=nsection | PRIOR_section=psection}
                       {,REV_file_type=rev_ftype}
                       {,ROLLBACK=rlabel}
                                                        1
                       {, SECtion='*' | 'section_name'}
                       {,WAIt=YES | NO}
                   1
                   References to COMMAND=SAVE, COMMAND=KEEP_SAVE,
               REV_FILE_TYPE, and sectioned records are not applicable to Windows.

Parameters:

               view_ref | view_id                                                           (Required)



               view_ref      A view specification where the reference is in the form [key=value] or
                             [set, member]. The forms [set, *] and [@cursor] are not allowed. A
                             view_ref is required for all commands except ADD. The commands
                             SAVE and KEEP_save (not applicable to Windows) require a view_ref
                             only if the document is present in the queue area or in the database.

               view_id       A view specification without a reference.




332  Command References
COMMAND=PUT | ADD | REPLACE | MERGE | CHANGE | SAVE | KEEP_save
                                                           (Optional)

Specifies how the record is to be imported. The default is PUT.


   PUT                If the record does not already exist in the database, the record is
                      added. If it does already exist, the existing record is replaced by
                      the imported record.

   ADD                The record is added if the record does not already exist in the
                      database. The record cannot already exist in the database.

   REPLACE            The record must already exist in the database. The existing record
                      is replaced by the imported record.

   MERGE              If the record does not already exist in the database, a PUT is
                      performed. If it already exists, a CHANGE is performed.

   CHANGE             The record must already exist in the database. A REPLACE is
                      performed. Sections and fields in the existing record that are not in
                      the imported record are not deleted.

   SAVE               Places the record into the queue area with a status of SAVE. If the
                      record already exists in the queue area, it is replaced by the
                      imported record. (This is not applicable to Windows.)

   KEEP_save          Places the record into the queue with a status of SAVE. If the
                      record already exists in the queue area, the fields that are not in the
                      imported record are not deleted. (This is not applicable to
                      Windows.)

CONVerter=converter                                                               (Optional)

Specifies the name of the converter to import the record. The stored converter name is
used when importing. This parameter is used only to override the stored converter.

For more information about converters, see Markup and Style Guide, “Converters.”




                                                               Command References  333
               DATA_file=fd                                                                     (Optional)

               Specifies the name of the data file to be imported. This is not used for a WP type of
               converter. The following gives the default file name for each system:



                Operating system         Default name

                NT                       impexp.dat

                UNIX                     impexp.dat

                VMS                      IMPEXP.DAT


               FINal_file=fd                                                                    (Optional)

               Specifies the final form document to be imported. This parameter is used only for WP
               converters.

               ERR=errlabel                                                                     (Optional)

               Specifies the label in the proc to branch to if the IMPORT/VIEW command fails.

               Note: If any of the specified term IDs are not in the result set, the system considers this
               to be a syntax error because it is caught during the parsing stage. Therefore, the system
               will not branch to the label indicated by the ERR parameter, which handles execution
               errors only. In the event of syntax errors, you can have the system transfer control to a
               label indicated by the ON/SYNTAX command.

               NEXT_section=nsection | PRIOR_section=psection                                   (Optional)

               Indicates whether the new section(s) from the import file is added before or after the
               specified section in the receiving document. The values for psection and nsection can be
               any of the existing sections in the receiving document. (Sectioned records are not
               applicable to Windows.)

               For example, if you specify PRIOR_section=SITES, the system adds the new sections(s)
               before the SITES section. If you specify NEXT_section=SITES, then the system adds the
               new section(s) after the SITES section.

               UNIX, VMS

               REV_file_type=rev_ftype                                                          (Optional)



334  Command References
              Specifies the revisable file type to be imported. This is used as the file extension for the
              revisable file. For example, if REV_FILE_TYPE='BLOB', then the revisable file that
              will be imported is FILE.BLOB. The REV_FILE_TYPE parameter is used only for WP
              converters. The default is WPL.

              All

              ROLLBACK=rlabel                                                                   (Optional)

              Specifies the label in the proc to branch to if the IMPORT/VIEW command is rolled back
              in a deadlock situation.

              SECtion= '*' | 'section_name'                                                     (Optional)

              Changes the name of the section being imported. The section name in the file (if any) is
              ignored. SECTION='*' must be used for files containing more than one section. The
              default is '*'. (Sectioned records are not supported by Windows.)

              WAIt=YES | NO                                                                     (Optional)

              Indicates whether the system waits for locked resources to become available. The default
              is YES.


              YES       The system waits for locked resources to become available.

              NO        The system does not wait for locked resources to become available when a lock
                        occurs, the command fails and DMSTAT is set to 867.


Prompt:
                    view_id or view_ref:
                    Change defaults (N/Y)?>

Key Points:
                   The IMPORT/VIEW command must be executed within a transaction.
                   The IMPort/View command returns the primary key of an added record in the global
                    variable DM_KEY_NAME and its value in the global variable DM_KEY_VALUE.




                                                                             Command References  335
Examples:

               Note: Results of the commands in the examples below may vary depending on the
               operating system and/or the version of BASIS that you are using.
               1.   In this first example, a new SCHED record is added to the database. Notice that the
                    view SCHED is specified without a reference. This is possible because
                    COMMAND=ADD.
                    FQM>
                    FQM> START/TRANSACTION PW=SCHED
                    FQM> IMPORT/VIEW SCHED, COMMAND=ADD
                    FQM> FINISH/TRANSACTION
                    FQM>
               2.   In this example, the EMPLOYEE record [ENO=1001] in the database is replaced by
                    the imported record.
                    FQM>
                    FQM> START/TRANSACTION PW=EMPLOYEE
                    FQM> IMPORT/VIEW [ENO=1001] EMPLOYEE, COMMAND=REPLACE
                    FQM> FINISH/TRANSACTION
                    FQM>
               3.   The following IMPort/View command places the SCHED record in the queue area
                    with a status of SAVE.
                    FQM>
                    FQM> START/TRANSACTION PW=SCHED
                                                                     1
                    FQM> IMPORT/VIEW SCHED, COMMAND=KEEP
                    FQM> FINISH/TRANSACTION
                    FQM>

                    1
                        COMMAND=KEEP is not applicable to Windows.




336  Command References
              LOGout
Purpose:

              To end a BASIS/FQM session and disconnect the terminal from the host computer.

Syntax:

              LOGout

Parameters:

              None.

Prompts:

              None.

Example:
                  FQM> LOGOUT
                  NORMAL TERMINATION - FQM

                  LINCOLN     logged out at 15-MAR-1989 09:32:20.99




                                                                       Command References  337
               LOOK
Purpose:

               To display a portion of a field‟s index terms. The index terms listed satisfy the criterion
               specified in the command. Result sets can be created by selecting terms in the list via the
               COMBine command. Use BACK to see a group of indexed terms preceding the last term
               displayed or MORE to see the next group of terms following or preceding the most recent
               term displayed.

Syntax:

               LOOK field_id=criterion
                      {,ADJacent=NO | YES}
                      {,COUnt=count}
                      {,CURsor=1:1000}
                      {,DROp=YES | NO}
                      {,END=elabel}
                      {,ERR=errlabel}
                      {,LIMit=1:20}
                      {,OUTput=YES | NO}
                      {,POSition=pos}
                      {,SAVe_look=NO | YES}
                      {,WAIt=YES | NO}

Parameters:

               field_id                                                                         (Required)

               Indicates the view name and field name in {<DB.model>}.view.field format.

               criterion                                                                        (Required)

               Indicates the criterion for selecting the terms from the field‟s index. The criterion must be
               in one of the forms


               value             A specific value, for example, 'ATLANTA'

               value:value       A range of values, for example, 'A':'CZZZ'




338  Command References
pattern            Use of wildcard in stems, for example 'TRAV'*

*                  Indicates all values.

If criterion has character value, enclose them within single quotation marks („‟). You can
specify wildcard characters before, within, or following a character string. Wildcard
characters are as follows: * for any group of characters, ? for any one character, or % for
zero or any one character.

ADJacent=NO | YES                                                                (Optional)

Indicates whether or not the system returns exact matches on the index terms. The default
is NO.


NO        No terms are displayed if none matches the criterion.

YES       Adjacent terms are displayed if no term matches the criterion. The criterion
          must be of the simple form value with no wildcards specified.

COUnt=count                                                                      (Optional)

Indicates the name of a global variable which is set to the number of terms displayed in
response to the LOOK command. This parameter is most often used in command
procedures but can be used interactively.

CURsor=1:1000                                                                    (Optional)

Indicates the number of the cursor established in the index. The cursor must be an integer
constant. The default is 9. Up to 60 cursors can be active at one time. These cursors
include OBTAIN and LOOK cursors for indexes.

DROp=YES | NO                                                                    (Optional)

Indicates whether the cursor is to be dropped from its previous index assignment and
reestablished according to the criterion of the current LOOK command.


YES       The cursor is dropped and then reestablished.

NO        The cursor is maintained according to its previous assignment.

The default is YES. You can override the default by using the SET/Defaults command.


                                                              Command References  339
               END=elabel                                                                       (Optional)

               Indicates the label within a command procedure to branch to if the end of the index is
               reached.

               ERR=errlabel                                                                     (Optional)

               Indicates the label within a command procedure to branch to if the LOOK command fails.

               LIMit=1:20                                                                       (Optional)

               Indicates the maximum number of terms that are displayed. The default is 20. You can
               override the default by using the SET/Defaults command to assign another value for
               LIMit.

               OUTput=YES | NO                                                                  (Optional)

               Indicates whether the system should suppress the screen output of the LOOK or
               BROWSE command. This feature is especially handy when you store the output in
               various proc variables by setting the SAVE_LOOK or SAVE_BROWSE parameter to
               YES. The default is YES.

               The possible values for this parameter are


               YES      The terms will be displayed on the screen.

               NO       The terms will not be displayed on the screen.

               POSition=pos                                                                     (Optional)

               Indicates the position of the term where the display begins. This parameter is typically
               used within command procedures.


                NEXT         The default for POSition is NEXT.

                             If DROP=YES, the system establishes the cursor and begins display with
                             the first term for the criterion specified and searches forward.

                             If DROP=NO, the system begins display with the term alphabetically or
                             numerically following the last term displayed.

                FIRST        If ADJacent=YES, if the system doesn‟t find value, it positions the cursor



340  Command References
                        LIMit/2 index terms prior to the criterion specified and searches forward.

                        If ADJacent=NO, the system positions the cursor at the first term for the
                        criterion specified and searches forward.

                        Terms are displayed in alphabetical or numerical order.

            LAST        If ADJacent=YES, the system positions the cursor n index terms past the
                        criterion specified and searches backward; n is the value for LIMit/2.

                        If ADJacent=NO, the system positions the cursor at the last term for the
                        criterion specified and searches backward.

                        Terms are displayed in reverse alphabetical or numerical order.

            PRIOR       If DROP=YES, the system establishes the cursor and begins the display
                        with the last term in the index.

                        If DROP=NO, the system begins display with the term alphabetically or
                        numerically preceding the last term displayed. This parameter is used
                        within command procedures more often than it is used interactively.

           SAVe_look=NO | YES                                                             (Optional)

           Indicates whether the terms should be saved as the values of global variables named
           DM_TERM_1, ... DM_TERM_20 and whether the reference counts should be saved as
           the values of global variables named DM_INFO_1, ... DM_INFO_20.


            NO       The terms and reference counts displayed are not saved as the values of global
                     variables.

            YES      The terms and reference counts displayed are saved as the values of global
                     variables.

           The default is NO. You can override the default by using the SET/Defaults command.

           WAIt=YES | NO

           Indicates whether the system should wait for locked records and resources to become
           available. The default is YES. You can override the default by using the SET/Defaults
           command.

Prompts:



                                                                        Command References  341
                   field_id:
                   criterion:
                   Change defaults (Y/N)? >

Key Points:
                  The LOOK command displays a portion of a field‟s index terms. The index terms
                   listed satisfy the criterion specified on the command. The criterion can be in one of
                   three forms. The forms and sample commands follow.


                    Criterion             Sample Commands

                    value                 LOOK EMPLOYEE.ENO = 1001

                                          LOOK EMPLOYEE.NAME = 'COHEN, SUSAN'

                    value:value           LOOK EMPLOYEE.ENO = 1001:9999

                                          LOOK EMPLOYEE.NAME = 'A':'JZZZ'

                    pattern               LOOK EMPLOYEE.ENO = *

                                          LOOK EMPLOYEE.NAME = *

                                          LOOK EMPLOYEE.NAME = 'J'*


               Note that a pattern of * (LOOK EMPLOYEE.ENO = *) is the only pattern allowed for
               use with numeric indexes. Therefore the command LOOK EMPLOYEE.ENO = 3* is
               not allowed. (See example 2.)
                  The LOOK command displays 4 columns of information including term ids,
                   members, references, and terms. The term id is a unique number from 1 to 20. Term
                   ids are used with the COMBine command to select the corresponding terms and
                   create result sets. (For more information, see the COMBine command description
                   earlier in this chapter.) The members indicate how many members contain that term.
                   The references indicate how many times the term occurs in the values of the named
                   field. Realize that a term can occur more than once in a single field value and that
                   each occurrence of the term is recorded in the reference count. Therefore reference
                   counts are not always the same as member counts.
                  The LIMit parameter indicates the maximum number of terms the LOOK command
                   displays. If fewer terms are found that satisfy the specified criterion, only those
                   terms are displayed followed by the message “End of information encountered”.
                   (See example 5.)




342  Command References
   When the LOOK command is used without the CURsor parameter (as is usually the
    case when using the command interactively), the cursor is assigned the number 9. A
    combination of up to 60 LOOK and OBTAIN cursors can be active simultaneously.
    Multiple cursors can be active within one field‟s index.
   The POSition parameter indicates whether the LOOK command begins scanning the
    index with the first or last term in the index. By scanning the index in a forward
    direction (POSITION=FIRST or POSITION=NEXT), the LOOK command displays
    terms in ascending order. By scanning the index in a backward direction
    (POSITION=LAST or POSITION=PRIOR) the LOOK command displays terms in
    descending order. A summary follows:


     Position           Cursor Initial Position       Search Direction

     FIRST              beginning                     forward

     NEXT               beginning or current          forward

     LAST               end                           backward

     PRIOR              end or current                backward


   When POSITION=FIRST or POSITION=LAST and DROP=YES, a new cursor is
    established in the index of the named field. If DROP=YES, then POSITION=NEXT
    is equivalent to POSITION=FIRST and POSITION=PRIOR is equivalent to
    POSITION=LAST. However, when DROP=NO and POSITION=NEXT or
    POSITION=PRIOR are used, the cursor is not reestablished. Instead, the LOOK
    command continues the display of terms beginning with the term following or
    preceding the last term displayed. (See example 11.)
   The cursor is positioned following the last term displayed by the LOOK command.
    The MORE and BACK commands also reposition the cursor and display additional
    terms in the index that satisfy the criterion specified on the LOOK command. (For
    additional information, see the MORE and BACK command descriptions in this
    chapter and example 11 below.)
   The COUnt parameter can be used to determine the actual number of terms
    displayed. The number of terms is stored as the value of the global variable named
    by the parameter.
   The SAVE_look parameter is used within command procedures to save the terms and
    the reference counts displayed as the values of global variables. The global variables
    are named DM_TERM_termid and DM_INFO_termid where termid is the number
    displayed in the first column of the term list. (See example 8.)




                                                             Command References  343
Examples:
               1.   You can enter the view name, field name, and criterion in response to the prompts
                    (a.) or with the command (b.).
               a.   FQM> LOOK
                    field_id: EMPLOYEE.ENO
                    criterion: 1001
                    Change defaults (N/Y)? > N
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1         1          1 1001
                    End of information was encountered.
               b.   FQM> LOOK EMPLOYEE.ENO=1001
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1            1 1001
                    End of information was encountered.
               2.   The criterion specified for numeric fields can specify a specific term (a.), a range of
                    terms (b.), or all terms (c.) in the index. A criterion including a stem and a wildcard
                    character (d.) is not allowed for numeric fields.
               a.   FQM> LOOK DEPARTMENT.DNO=101
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 101
                    End of information was encountered.
               b.   FQM> LOOK DEPARTMENT.DNO=101:301
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 101
                          2        1           1 201
                          3        1           1 202
                          4        1           1 301
                    End of information was encountered.
               c.   FQM> LOOK DEPARTMENT.DNO=*
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 100
                          2        1           1 101
                          3        1           1 201
                          4        1           1 202
                          5        1           1 301
                          6        1           1 302
                          7        1           1 401
                          8        1           1 501
                          9        1           1 601
                    End of information was encountered.
               d.   FQM> LOOK DEPARTMENT.DNO=3*




344  Command References
     USER ERROR( 676). Please check the specified search
     criterion.
     Cursor 9 was dropped.
3.   The criterion specified for character fields must be enclosed within single quotation
     marks ('). The criterion can identify a specific term (a.) or a range of terms from the
     index (b.). The range 'A':'D' displays those terms beginning with the letters 'A'
     through 'C' and terms beginning with 'D' (D followed by a blank). :'DZZZ' is required
     for the end range in order to display terms beginning with 'DA','DB','DC', etc. The
     criterion can identify stems by using the wildcard characters * and/or ? prior to,
     embedded within, or following the character stem (c.), (d.) and (e.).
a.   FQM> LOOK SCHED.DESTIN='PITTSBURGH'
     Term id Members References Term
     ------- ------- ---------- ----
           1        3           3 PITTSBURGH
     End of information was encountered.
b.   FQM> LOOK SCHED.DESTIN='A':'DZZZ'
     Term id Members References Term
     ------- ------- ---------- ----
           1        3           3 ATLANTA
           2        1           1 BAHAMAS
           3        1           1 BALTIMORE
           4        1           1 BOSTON
           5        1           1 BUFFALO
           6        1           1 CARACAS
           7        1           1 CHARLOTTE
           8        1           1 CHICAGO
           9        2           2 CINCINNATI
          10        2           2 DALLAS
          11        1           1 DAYTON
          12        1           1 DETROIT
          13        2           2 DULUTH
     End of information was encountered.
c.   FQM> LOOK SCHED.DESTIN=*'A'
     Term id Members References Term
     ------- ------- ---------- ----
           1        3            3 ATLANTA
           2        1            1 OTTAWA
           3        4            4 PHILADELPHIA
           4        1            1 ST. LUCIA
           5        1            1 TAMPA
     End of information was encountered.




                                                              Command References  345
               d.   FQM> LOOK SCHED.DESTIN='A'*
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        3            3 ATLANTA
                    End of information was encountered.
               e.   FQM> LOOK SCHED.DESTIN='DALLA'?
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        2           2 DALLAS
                    End of information was encountered.
               f.   FQM> LOOK SCHED.DESTIN='DA'%%%'AS'
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        2           2 DALLAS
                    End of information was encountered.
               4.   You can use the LOOK command to view the terms of indexed fields only.
                    FQM> LOOK CLIENT.CNAME='A'*
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1            1 AMMILLION, JUAN
                          2        1            1 AMUK, RON
                          3        1            1 AYE, PERRY
                    End of information was encountered.
               5.   The LIMit parameter specifies the maximum number of terms the LOOK command
                    displays. If additional terms are available that satisfy the criterion, the last term is
                    followed by the FQM> prompt (a.). In this situation, you can use the MORE
                    command to view the additional terms. Often there are fewer terms found that satisfy
                    the criterion (b.) than the number of terms specified on the LIMit parameter. In this
                    situation, only those terms that satisfy the criterion are displayed followed by the
                    message “End of information encountered.” A subsequent MORE command would
                    display the same message.
                    FQM> LOOK EMPLOYEE.ENO=*,LIMIT=5
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 1001
                          2        1           1 1823
                          3        1           1 2312
                          4        1           1 2458
                          5        1           1 2843
                    FQM> MORE
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 2930
                          2        1           1 2939
                          3        1           1 3395
                          4        1           1 3724
                          5        1           1 3912




346  Command References
     FQM> LOOK EMPLOYEE.NAME='SMITH'*,LIMIT=5
     Term id Members References Term
     ------- ------- ---------- ----
           1        1           1 SMITH, CASEY
           2        1           1 SMITH, JOHN
           3        1           1 SMITH, NANCY
     End of information was encountered.
6.   The criterion specified for numeric fields can specify a specific term (a.). When you
     do not supply the CURsor parameter with the LOOK command, the cursor number 9
     is used (b.). Up to 60 LOOK and OBTAIN cursors can be active simultaneously. To
     establish a cursor number other than 9, use the CURsor parameter in your LOOK
     command (c.). The * displayed to the left of the cursor numbers in the
     SHow/Look_cursors chart indicates the current cursor number. Notice that the last
     cursor established is the current cursor (d.). The current cursor is used by subsequent
     MORE and BACK commands that do not specify the CURsor parameter.
     Subsequent LOOK commands that do not specify the CURsor parameter use the
     cursor number 9, regardless of the number of the current cursor.
a.   FQM> LOOK DEPARTMENT.DNO=101
     Term id Members References Term
     ------- ------- ---------- ----
           1        1           1 101
     End of information was encountered.
b.   FQM> SHOW/LOOK_CURSORS
     Cursor Limit Wait Save Field Index
     ------ ----- ---- ---- -----------
     * 9     20   YES   NO <TOUR.ALL>DEPARTMENT.DNO
            Criterion: 101
     Note: * indicates current LOOK cursor.
c.   FQM> LOOK EMPLOYEE.NAME='SMITH'*,CURSOR=8
     Term id Members References Term
     ------- ------- ---------- ----
           1        1           1 SMITH, CASEY
           2        1           1 SMITH, JOHN
           3        1           1 SMITH, NANCY
     End of information was encountered.
d.   FQM> SHOW/LOOK_CURSORS
     Cursor Limit Wait Save Field Index
     ------ ----- ---- ---- -----------
        9    20   YES   NO <TOUR.ALL>DEPARTMENT.DNO
            Criterion: 101
     * 8     20   YES   NO <TOUR.ALL>EMPLOYEE.NAME
            Criterion: 'SMITH'*
     Note: * indicates current LOOK cursor.




                                                               Command References  347
               7.   The COUnt parameter supplies the name of the global variable that is assigned the
                    number of terms displayed.
                    FQM> LOOK EMPLOYEE.NAME='A'*,COUNT=ACNT
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 ACHILLES, HAROLD
                          2        1           1 ADAMS, PAULA
                          3        1           1 ALTMAN, MARY
                          4        1           1 ANGELLO, LUKE
                    End of information was encountered.
                    FQM> SHOW/GV ACNT
                       ACNT = 4
               8.   The SAVE=YES parameter indicates the terms and reference counts displayed are
                    saved as the values of global variables named DM_TERM_1, DM_TERM_2, etc.
                    and DM_INFO_1, DM_INFO_2, etc., respectively.
                    FQM> LOOK EMPLOYEE.DNO=*,LIMIT=4,SAVE_LOOK=YES
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        9           9 100
                          2       12          12 101
                          3       20          20 201
                          4       13          13 202
                    FQM> SHOW/GV DM_TERM_*
                       DM_TERM_1 = 100
                       DM_TERM_2 = 101
                       DM_TERM_3 = 201
                       DM_TERM_4 = 202
                    FQM> SHOW/GV DM_INFO_*
                       DM_INFO_1 = 9
                       DM_INFO_2 = 12
                       DM_INFO_3 = 20
                       DM_INFO_4 = 13




348  Command References
9.   The references column of the LOOK command chart displays the number of times
     the term appears in the values of the named field. The number of references does not
     always reflect the number of members. In this example, the COMBine command is
     followed by the term id 1, indicating that the view record indexed under the term
     “BRITISH VIRGIN ISLANDS” is to be collected into a result set.
     FQM> LOOK PLACE.LOCATION=*'ISLANDS'
     Term id Members References Term
     ------- ------- ---------- ----
           1        1           1 BRITISH VIRGIN ISLANDS
           2        1           1 CAYMAN ISLANDS
           3        1           1 VIRGIN ISLANDS
     End of information was encountered.
     FQM> COMBINE 1
           Result set 1 contains 1 references to 1 members.
10. The POSition parameter indicates the original position of the cursor and the direction
    in which the index is processed. Notice that POSITION='FIRST' results in the
    display of the terms in ascending alphabetical or numerical order and
    POSITION='LAST' results in the display of the terms in descending order. The final
    position of the cursor is always at the last term displayed.
     FQM> LOOK DEPARTMENT.DNO=*,POSITION='FIRST'
     Term id Members References Term
     ------- ------- ---------- ----
           1        1           1 100
           2        1           1 101
           3        1           1 201
           4        1           1 202
           5        1           1 301
           6        1           1 302
           7        1           1 401
           8        1           1 501
           9        1           1 601
     End of information was encountered.
     FQM> LOOK DEPARTMENT.DNO=*,POSITION='LAST'
     Term id Members References Term
     ------- ------- ---------- ----
           1        1           1 601
           2        1           1 501
           3        1           1 401
           4        1           1 302
           5        1           1 301
           6        1           1 202
           7        1           1 201
           8        1           1 101
           9        1           1 100
     End of information was encountered.




                                                             Command References  349
               11. To establish a cursor in an index, use POSITION=FIRST and DROP=YES on the
                   LOOK command. To continue the display of terms that meet the original criterion,
                   enter a MORE command (a.). The command LOOK using POSITION=NEXT and
                   DROP=NO would produce the same result. The second LOOK command is
                   equivalent to a MORE command (b.).
               a.   FQM> LOOK EMPLOYEE.NAME='S'*,LIMIT=5,POSITION=FIRST,DROP=YES
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 SABOE, MIKE
                          2        1           1 SARCHIN, TONY
                          3        1           1 SCHAUER, RACHEL
                          4        1           1 SCHMIDT, MARVIN
                          5        1           1 SCHMIDT, RANDY
                    FQM> MORE
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 SCHREIBER, ROY
                          2        1           1 SEUFERT, TODD
                          3        1           1 SHELTON, JOSHUA
                          4        1           1 SIGMAN, RICH
                          5        1           1 SMITH, CASEY
               b.   FQM> LOOK EMPLOYEE.NAME='S'*,LIMIT=5,POSITION=NEXT,DROP=NO
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 SMITH, JOHN
                          2        1           1 SMITH, NANCY
                          3        1           1 SPEIDEL, TOMMY
                          4        1           1 STEIN, MINDY
                          5        1           1 STOCKER, HAZEL




350  Command References
              MAKE/View                                                              (FQM only)
Purpose:

              To initialize a user buffer to the specified view definition.

Syntax:

              MAKE{/View} viewbuf_id {, ERR=errlabel}

Parameters:

              viewbuf_id                                                                           (Required)

              Specifies the user buffer to be initialized and the view definition used to initialize it.

              ERR=errlabel                                                                         (Optional)

              Specifies the label in a proc to branch to if the MAKE/View command fails.

              Note: If any of the specified term IDs are not in the result set, the system considers this
              to be a syntax error because it is caught during the parsing stage. Therefore, the system
              will not branch to the label indicated by the ERR parameter, which handles execution
              errors only. In the event of syntax errors, you can have the system transfer control to a
              label indicated by the ON/SYNTAX command.

Prompts:
                  viewbuf_id:
                  Change defaults (Y/N)?>

Key Points:
                 You must execute the MAKE/View command before you add a new view record to a
                  database. This command formats the user buffer according to the specified view
                  definition. You can then build a view record in the user buffer by supplying the field
                  values through ASSIGN/Field commands. Once the user buffer contains the
                  complete view record, you can use an ADD/View command to add the record to the
                  database.
                 Since you use the MAKE/View command with the ADD/View command, you must
                  specify a view definition that includes all source record fields that are defined as
                  required in the Actual Data Model (OCCURS=1:n). If you use a view definition that
                  lacks any required fields, the ADD/View command violates the data integrity
                  constraints and the system does not add the record to the database.




                                                                               Command References  351
                  You must use a transaction to execute the MAKE/View, ASSIGN/Field, and
                   ADD/View commands.

Example:

               In this proc, the MAKE/View command initializes user buffer B to a view definition
               called ASSIGNMENT. If the system cannot perform this initialization, it transfers
               control to the label MAKERR.

                   Proc Segment:
                   LOOP:
                      START/TRANSACTION PW=ASSIGNMENT
                   *
                      MAKE/VIEW ASSIGNMENT@B,ERR=MAKERR
                      TELL 'Enter new assignment data:',$S2
                      INQUIRE/PV ENO, 'Enter the employee number> '
                      INQUIRE/PV PROJ, 'Enter the project name> '
                      INQUIRE/PV HOUR, 'Enter the number of hours> '
                   *
                      ASSIGN/FIELD ENO@B='!ENO!'
                      ASSIGN/FIELD PROJ_NAME@B='!PROJ!'
                      ASSIGN/FIELD HOURS@B='!HOUR!'
                      ADD/VIEW ASSIGNMENT@B,WAIT=YES,ERR=ADDERROR
                      FINISH/TRANSACTION
                         :
                         :
                   MAKERR:
                      SHOW/MESSAGE !DMSTAT!
                      ABORT/TRANSACTION
                      RETURN




352  Command References
              MORE
Purpose:

              To display the next group of terms alphabetically or numerically following or preceding
              the most recent term displayed by the current BROWSE, LOOK, MORE, or BACK
              command or pointed to by the most recently set BROWSE or LOOK cursor.

Syntax:

              MORE {criterion} {,CURsor=0:60} {,END=elabel} {,ERR=errlabel}

Parameters:

              criterion                                                                       (Optional)

              Indicates the criterion for selecting the terms from the thesaurus named by the BROWSE
              command or from the index of the field named by the LOOK command. The criterion
              can be in one of three forms

                  value          A specific value.
                  value:value    A range of values.
                  pattern        Use of * and ? in stems.

              If a criterion is not supplied, the criterion specified on the BROWSE or LOOK command
              that established the cursor is assumed.

              CURsor=0:60                                                                     (Optional)

              Indicates the number of a cursor established by a LOOK command. The cursor must be
              an integer constant. If not specified, the cursor number established by the last BROWSE
              or LOOK command executed is used. The default is 9. There can be as many as 60
              cursors active for the BROWSE and LOOK commands.

              END=elabel                                                                      (Optional)

              Indicates the label within a command procedure to branch to if the end of the index is
              reached.

              ERR=errlabel                                                                    (Optional)

              Indicates the label within a command procedure to branch to if the MORE command fails.

Prompts:


                                                                           Command References  353
               None. The index, criterion, and cursor number specified on the most recent BROWSE or
               LOOK command are used.

Key Points:
                  The BROWSE and LOOK commands assign a number to a cursor and use the cursor
                   to display all or a portion of the terms found in a thesaurus or in a field‟s index.
                   FQM uses the BROWSE cursor or the LOOK cursor, depending on which command,
                   BROWSE or LOOK, was most recently entered. The BROWSE and LOOK
                   commands establish other attributes associated with displaying term lists, such as the
                   maximum number of terms displayed.
                  If all of the terms in a thesaurus or field‟s index have not been displayed, the MORE
                   command can be used to display additional terms. The MORE command displays
                   the next group of terms alphabetically or numerically following the last term
                   displayed by a BROWSE, LOOK, MORE or BACK command.
                  The cursor number assigned to an index by the last BROWSE or LOOK command
                   executed is called the current cursor. If the CURsor parameter is not used on the
                   MORE command to supply a specific cursor number, the “current cursor” is used.
                  The attributes established by a BROWSE or LOOK command used by the MORE
                   command include:
                    -      Use of a specific thesaurus or field‟s index,

                    -      The criterion,

                    -      The maximum number of terms listed (LIMIT parameter),

                    -      The name of the global variable, if any, assigned the number of terms actually
                           displayed (COUNT parameter), and

                    -      The terms and reference counts (if saved) are displayed as the values of global
                           variables (SAVe_BROWSE and SAVe_LOOK parameters).

               Of these attributes, only the criterion can be changed on the MORE command. (See
               example 4.)




354  Command References
Examples:
            1.   The BROWSE or LOOK command assigns cursor number 9 (by default) to the ENO
                 field index. The current cursor is the cursor named by the last BROWSE or LOOK
                 command executed. Therefore the current cursor is cursor number 9 in this example.
                 Because of the LIMit parameter, five terms are displayed. The current cursor is
                 positioned after the last term displayed. Unless otherwise specified, the MORE
                 command uses the current cursor and the criterion and LIMIT value associated with
                 that cursor. Therefore, the MORE command displays the terms following the current
                 cursor position in the ENO field.
                 FQM> LOOK EMPLOYEE.ENO=*,LIMIT=5
                 Term id Members References Term
                 ------- ------- ---------- ----
                       1        1           1 1001
                       2        1           1 1823
                       3        1           1 2312
                       4        1           1 2458
                       5        1           1 2843

                 FQM> MORE
                 Term id Members         References      Term
                 ------- -------         ----------      ----
                       1       1                  1      2930
                       2       1                  1      2939
                       3       1                  1      3395
                       4       1                  1      3724
                       5       1                  1      3912
            2.   Multiple cursors can be active simultaneously. The last cursor established is called
                 the current cursor. If the CURsor parameter is not used on the MORE command, the
                 current cursor is used. Following the first LOOK command in this example the
                 current cursor is numbered 1. Following the second LOOK command the current
                 cursor is numbered 2. The first MORE command does not specify a cursor and
                 therefore uses the current cursor (the cursor numbered 2). The second MORE
                 command supplies the cursor number used.




                                                                         Command References  355
                    FQM> LOOK EMPLOYEE.NAME='M'*,LIMIT=5,CURSOR=1
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 MAIR, ALICE
                          2        1           1 MARTIN, MARK
                          3        1           1 MARTIN, PETER
                          4        1           1 MASON, PERRY
                          5        1           1 MCCORMICK, WILLIE

                    FQM> LOOK EMPLOYEE.DNO=*,LIMIT=5,CURSOR=2
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        9           9 100
                          2       12          12 101
                          3       20          20 201
                          4       13          13 202
                          5       21          21 301

                    FQM> MORE
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1       10          10 302
                          2       19          19 401
                          3       12          12 501
                          4       14          14 601
                    End of information was encountered.

                    FQM> MORE CURSOR=1
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 MCNALLY, WENDY
                          2        1           1 MILLER, JOHN
                          3        1           1 MILLS, GLENN
                          4        1           1 MORAN, DAN
                          5        1           1 MULLICK, STACEY
                    End of information was encountered.
               3.   The LOOK command specifies the criterion ('K'*) of the terms listed. The end of
                    information is reached because all of the terms that satisfy the criterion have been
                    displayed. If you enter the MORE command without parameters, FQM uses the
                    criterion specified on the last BROWSE or LOOK command. The first MORE
                    command results in an end of information message because the original LOOK
                    command criterion ('K'*) is used. The second MORE command specifies a new
                    criterion (*), indicating that terms following the current cursor position are to be
                    displayed. Notice that the terms displayed begin with letters other than 'K' because
                    the criterion * (any term) is used. Because the third MORE command uses the
                    criterion ('K'*) that originated with the LOOK command, the end of information
                    message is displayed again. The final MORE command returns terms that follow the
                    current cursor position.




356  Command References
FQM> LOOK EMPLOYEE.NAME='K'*,LIMIT=6
Term id Members References Term
------- ------- ---------- ----
      1        1           1 KANG, SAM
      2        1           1 KELLY, CINDY
      3        1           1 KONOPKA, ALLEN
      4        1           1 KRENZKE, MARY
      5        1           1 KUNCHAL, KURT
End of information was encountered.

FQM> MORE
End of information was encountered.

FQM> MORE *
Term id Members   References   Term
------- -------   ----------   ----
      1       1            1   LAPP, RUSSELL
      2       1            1   LEIGHTON, LISA
      3       1            1   LEMON, LINDA
      4       1            1   LEWIS, BILL
      5       1            1   LIN, ANN
      6       1            1   LONG, TOM

FQM> MORE
End of information was encountered.

FQM> MORE *
Term id Members   References   Term
------- -------   ----------   ----
      1       1            1   LOVE, ALLEN
      2       1            1   LUKENS, WILMA
      3       1            1   LYONS, JEANNE
      4       1            1   MAIR, ALICE
      5       1            1   MARTIN, MARK
      6       1            1   MARTIN, PETER




                                           Command References  357
               4.   The LOOK command specifies the criterion ('B'*) of the terms listed. If you enter
                    the MORE command without parameters, FQM uses the criterion specified on the
                    last BROWSE or LOOK command. The first MORE command displays the terms
                    alphabetically following the last term displayed by the LOOK command. The second
                    MORE command specifies a new criterion ('P'*), indicating that terms beginning with
                    the letter 'P' are displayed.
                    FQM> LOOK EMPLOYEE.NAME='B'*,LIMIT=5
                    Term id Members References Term
                    ------- ------- ---------- ----
                          1        1           1 BAHAM, GEORGE
                          2        1           1 BALUKJIAN, HENRY
                          3        1           1 BARNETT, DON
                          4        1           1 BARTICK, HARRIETT
                          5        1           1 BECK, GARY

                    FQM> MORE
                    Term id Members        References      Term
                    ------- -------        ----------      ----
                          1       1                 1      BERT, CARL
                          2       1                 1      BLACK, THOMAS
                          3       1                 1      BODNARUK, ANN
                          4       2                 2      BREKHOVSKIKH, LARRY
                          5       1                 1      BROWN, SANDRA

                    FQM> MORE 'P'*
                    Term id Members        References      Term
                    ------- -------        ----------      ----
                          1        1                1      PANZER, RITA
                          2        1                1      PECKHAM, PATTY
                          3        1                1      PETERS, BRENDA
                          4        1                1      PHOENIX, SUNNY
                          5        1                1      PIZZINO, JUDY




358  Command References
              OBTAIN/View                                                         (FQM only)
Purpose:

              To read view records that have indexed keys. Any field that has an index maintained for
              it can be used as an “obtain field.” The OBTAIN/View command gives you direct access
              to any view record through an indexed field value.

Syntax:

              OBTAIN{/View} fieldbuf_id {=value | , POSITION=position}
                    {,BREAK=blabel}
                    {,BREAK_LEVEL=blevel}
                    {,CURSOR=cursor}
                    {,END=elabel}
                    {,ERR=errlabel}
                    {,INTENT=CURRENT | UPDATE | READ | CHECKOUT}
                    {,KEY=key}
                    {,POS_LEVEL=plevel}
                    {,ROLLBACK=rlabel}
                    {,WAIt=YES | NO}

Parameters:

              fieldbuf_id                                                                       (Required)

              Specifies the indexed field to use as the “obtain field” and the buffer which holds the
              obtained view record.

              value                                                                              (Optional)

              Specifies the “obtain value” used as the search key. A single view record is returned if
              one or more view records contain the specified value. A cursor in the index is established
              regardless of whether a view record is returned or not.

              BREAK=blabel                                                                       (Optional)

              Specifies the label in a proc to branch to if the returned view record contains a different
              obtain value than the last view record returned.




                                                                              Command References  359
               BREAK_LEVEL=blevel                                                                (Optional)

               Specifies the proc variable that is set to the lowest level at which a key break occurs. The
               variable is set only when the OBTAIN/View command returns the status code
               DMSTAT.KEY_BREAK. The BREAK_LEVEL parameter is meaningful only when an
               obtain by position is processing a hierarchical view definition.

               CURSOR=cursor                                                                     (Optional)

               Specifies the number of the cursor assigned to the index. The cursor must be an integer
               constant from 1 to 1000. If the CURSOR parameter is not specified, a cursor number of 1
               is used.

               END=elabel                                                                        (Optional)

               Specifies the label in a proc to branch to if the system reaches the end of the index.

               ERR=errlabel                                                                      (Optional)

               Specifies the label in a proc to branch to if the OBTAIN/View command fails.

               Note: If any of the specified term IDs are not in the result set, the system considers this
               to be a syntax error because it is caught during the parsing stage. Therefore, the system
               will not branch to the label indicated by the ERR parameter, which handles execution
               errors only. In the event of syntax errors, you can have the system transfer control to a
               label indicated by the ON/SYNTAX command.

               INTENT=CURRENT | UPDATE | READ | CHECKOUT                                         (Optional)

               Indicates how you intend to access the view record. The default is CURRENT.


               CURRENT              The view record is used in the manner specified on the last active
                                    START/TRANsaction command for this view definition.

               UPDATE               The view record is locked when it is read so an update can occur.
                                    When INTENT=UPDATE is used, the OBTAIN/View command
                                    must be used within a transaction (after a START/TRANsaction
                                    and before a FINISH/TRANsaction command or
                                    ABORT/TRANsaction command).

               READ                 The view record is read only. An update cannot occur.




360  Command References
CHECKOUT             The view record is locked as it is read so an update can occur. In
                     addition to the lock, the view record is marked as checked out in the
                     queue area. Checkout intent should only be issued inside a
                     transaction. This intent is usually used when extended editing is to
                     take place because once the transaction has been FINISHed, the
                     view record is still “checked out” so that the record will not be
                     updated by others until it has been checked back in.

KEY=key                                                                             (Optional)

Specifies the proc variable in which the system stores the returned obtain value.

POSITION=position                                                                   (Optional)

Specifies the position of the cursor in the index. The default is NEXT.


FIRST                     Return the first view record that contains the lowest obtain
                          value.

LAST                      Return the last view record that contains the highest obtain
                          value.

NEXT                      Return the next view record that contains the “current” obtain
                          value or the first view record that contains the next higher
                          obtain value. If a cursor is not already set, POSITION=NEXT
                          acts the same as POSITION=LAST.

PRIOR                     Return the previous view record that contains the “current”
                          obtain value or the last view record that contains the next
                          lower obtain value. If a cursor is not already set,
                          POSITION=PRIOR acts the same as POSITION=LAST.

NEXT_DIFFERENT            Returns the next view record that contains the next higher
                          obtain value.

PRIOR_DIFFERENT           Returns the next view record that contains the next lower
                          obtain value.

POS_LEVEL=plevel                                                                    (Optional)

Specifies the level in the hierarchical view definition at which positioning is supposed to
occur. The plevel must be an integer from 0 to 12. The POS_LEVEL parameter is




                                                               Command References  361
               meaningful only when an OBTAIN by position is processing a hierarchical view. If the
               POS_LEVEL parameter is not specified, the value 0 is used.

               ROLLBACK=rlabel                                                                  (Optional)

               Specifies the label in a proc to branch to if the OBTAIN/View command is rolled back in
               a deadlock situation.

               WAIt=YES | NO                                                                    (Optional)

               Indicates whether the system waits for locked records. The default is YES.


               YES          The system waits for locked records to become available.

               NO           The system does not wait for locked records to become available. When a
                            lock occurs, the command fails and DMSTAT is set to 867.


Prompts:
                    fieldbuf_id{=value}:
                    Change defaults (Y/N)? >

Key Points:
                   The OBTAIN/View command accesses view records through associated indexed
                    values (search keys). The system stores an obtained view record in a user buffer.
                    You can use OBTAIN/View commands within or outside of transactions.
                   Any field that has an index maintained for it can be used as an “obtain field”. The
                    OBTAIN/View command establishes a cursor (or pointer) in the index. The cursor
                    indicates which view record was read last (the “current view”). Unless you use the
                    CURSOR parameter to specify another number, the system sets the cursor to 1.
                   There are usually three steps involved in using the OBTAIN/View command:


                     1.    Establish the cursor, using the “obtain by position” or “obtain by value”
                           method.

                     2.    Reposition the cursor using the “obtain by position” method.

                     3.    Drop the cursor when you are done using the index.

                   To establish a cursor “by position”, you use the POSITION=FIRST or
                    POSITION=LAST parameter in the OBTAIN/View command. The
                    POSITION=FIRST parameter indicates the “index value list” is processed from the



362  Command References
    lowest to the highest obtain value. The POSITION=LAST parameter indicates the
    “index value list” is processed from the highest to the lowest obtain value. The
    system establishes the cursor and names it according to the CURSOR parameter.
    The cursor accesses either the highest or lowest obtain value.
   To establish a cursor “by value”, set the named field equal to a specific value (i.e.
    DNO=101). The cursor is established, named according to the CURSOR parameter,
    and accesses the first view record (possibly the only view record) associated with the
    specified obtain value. If the specified field value does not exist in the index, the
    system positions the cursor to the next highest value (and the ERR path is taken, if
    the command is used in a proc).
   Note that the “obtain by value” method establishes a starting point in the “index value
    list.” For example, OBTAIN/View commands that follow an initial OBTAIN/View
    “by value” command does not “return” only those view records associated with the
    specified value. Subsequent OBTAIN/View commands can access view records
    associated with higher or lower DNO values (if such values exist).
   Once you establish a cursor, subsequent OBTAIN/View commands use the
    POSITION=NEXT, POSITION=PRIOR, POSITION=NEXT_DIFFERENT, or
    POSITION=PRIOR_DIFFERENT parameter to indicate how the cursor moves
    through the “index value list.” The POSITION parameter allows the system to
    process the entire “index value list.” When the system reaches the end of the index, it
    issues an “end-of-information” code (DMSTAT=1). If the OBTAIN/View command
    is used in a proc, the system transfers control to the label specified in the END
    parameter.
   You can test the returned index value if you want to process only a portion of the
    index values. The KEY parameter indicates the proc variable in which the returned
    index value is stored. You can test the proc variable value to determine if processing
    should continue.
   You must drop the cursor when the OBTAIN/View processing is complete. The
    DROP/CURSOR command serves this purpose.
   You can use the OBTAIN/View command within a transaction. Transactions use the
    INTENT, WAIT and ROLLBACK parameters. (The ROLLBACK parameter is only
    used within a proc.)
   You can establish cursors within or outside a transaction. Within a transaction, you
    can use an [@cursor] reference to access a cursor established outside a transaction.
    You can not use an OBTAIN/View command to move a cursor that was established
    outside an transaction inside a transaction. A cursor established outside a transaction
    cannot be repositioned within a transaction (by an OBTAIN/View command).
   The system automatically drops all cursors established within a transacton when the
    transaction is finished (by the FINISH/TRANsaction command) or aborted (by the
    ABORT/TRANsaction command).




                                                              Command References  363
                     If an entire index is deleted, any cursors established outside a transaction on the
                      index before it was deleted are invalid. Those cursors should be dropped (see the
                      “DROP/Cursor” command above in this chapter).
                     Table 6-6 shows what happens to a record in a particular state and a given action:

                 Table 6-6: Effects of various GET intents on records in various states


                 UNIX, VMS

   Current           INTENT=       INTENT=         INTENT=          INTENT=            INTENT=
                                                         5
   State             READ          QREAD           QREAD            CHECKOUT           UPDATE
                          1            2               2                       3           2
   READY             DB            Q               Q                QCHECK             Q
                          1                1           4                       3                         4
   SAVED             DB            DB              Q                QCHECK             Q (still saved)
                          1            2               2
   CHECKOUT DB                     Q               Q                error              error
   previous
   state
   READY
                          1                1           4
   CHECKOUT DB                     DB              Q                error              error
   previous
   state not
   READY
                          1                1                                       6           1
   in database       DB            DB              error            DBCHECK            DB

                 Windows

   Current           INTENT=        INTENT=         INTENT=         INTENT=  INTENT=
                                                          5
   State             READ           QREAD           QREAD           CHECKOUT UPDATE
                              1                1
   CHECKOUT          DB             DB              N/A             ERROR              ERROR
                              1                1                                   6           1
   in database       DB             DB              N/A             DBCHECK            DB




364  Command References
                 1
                     DB means the record comes from the database.
                 2
                     Q means the record comes from the queue.
                 3
                   QCHECK means the record comes from queue and, if the user has HOLD
            privilege, is checked out.
                 4
                   The record comes from queue if one of the 3 following conditions is met: (1) the
            user checked out or saved the record, or (2) the user has UNHOLD privilege, or (3) the
            user ID in the queue status record is $NOUID. Otherwise, an error occurs.
                 5
                   This special case of INTENT=QREAD is for the following situation: the reference
            spec is [set,member] and the record resides in the queue only.
                 6
                DBCHECK means that the record comes from the database and, if the user has
            HOLD privileges, is checked out.

Examples:
            1.   This example shows how you can use the POSITION parameter with the
                 OBTAIN/View command to move the cursor to the next or previous position in the
                 index.
                                                                1
                 FQM> OBTAIN/VIEW EMPLOYEE.ENO=10034
                 FQM> TYPE NAME,ENO,JOB,BUFFER=A,LABEL=NO

                 KANG, SAM      10034    Administrative Assistant
                                                                                2
                 FQM> OBTAIN/VIEW EMPLOYEE.ENO, POSITION=PRIOR
                 FQM> TYPE NAME,ENO,JOB,BUFFER=A,LABEL=NO

                 HELMICK, CURT       10033    Salesman
                                                                            3
                 FQM> OBTAIN/VIEW EMPLOYEE.ENO, POSITION=NEXT
                 FQM> TYPE NAME,ENO,JOB,BUFFER=A,LABEL=NO

                 KANG, SAM      10034    Administrative Assistant

                 FQM> DROP/CURSOR CURSOR=1




                                                                        Command References  365
                    1
                     The OBTAIN/View command establishes a cursor in the ENO index at the view
               record associated with the ENO value of 10034. The view record is stored in user buffer
               A.
                    2
                      The POSITION=PRIOR parameter on the second OBTAIN/View command moves
               the cursor to the next lowest ENO value (or 10033). The view record associated with the
               10033 ENO value is stored in user buffer A.
                    3
                      The POSITION=NEXT parameter on the third OBTAIN/View command moves
               the cursor to the next highest value (or 10034). This is the original cursor position.
               2.   This proc uses OBTAIN/View commands to change the MGR_NO field value of all
                    EMPLOYEE records in which the DNO field contains the value 101.

                    Proc Segment:
                    START/TRANSACTION PW=EMPLOYEE
                    OBTAIN/VIEW +
                    EMPLOYEE.DNO@B=101,INTENT=CURRENT,END=OBT1END, +
                                1
                    ERR=OBT1ERR
                    *
                    LOOP:
                       ASSIGN/FIELD MGR_NO@B=5519
                       PUT/VIEW [@1]EMPLOYEE@B,ERR=PUTERR
                       OBTAIN/VIEW EMPLOYEE.DNO@B,POSITION=NEXT, +
                                         2
                       INTENT=CURRENT,+
                       BREAK=DCURSOR,END=DCURSOR,ERR=OBT2ERR
                    JUMP LOOP
                    *
                    DCURSOR:
                       FINISH/TRANSACTION
                       DROP/CURSOR CURSOR=1
                       RETURN
                    *
                    OBT1END:
                       SHOW/MESSAGE !DMSTAT!
                       TELL '(THE DNO INDEX IS EMPTY)'
                       ABORT/TRANSACTION
                       RETURN
                    *
                    OBT1ERR:
                       SHOW/MESSAGE !DMSTAT!
                       TELL '(THERE ARE NO DNO''S WITH VALUE OF 101)'
                       ABORT/TRANSACTION
                       RETURN
                    *




366  Command References
     OBT2ERR:
        SHOW/MESSAGE !DMSTAT!
        TELL '(THE CURSOR STOPPED NEAR THIS POSITION)'
        TYPE DNO,ENO,NAME,BUFFER=B,LABEL=NO
        ABORT/TRANSACTION
        RETURN
           :
           :

     1
        The first OBTAIN/View command establishes the cursor (default cursor number 1)
using the “obtain by value” method. The cursor accesses the first view record associated
with the specified value and stores that record in user buffer B. (If the value 101 does not
exist in the DNO index, control branches to the OBT1ERR label and the cursor accesses
the next highest DNO value.) The PUT/View command uses an OBTAIN cursor
reference [@1] to put the changed view record into the database.
     2
       The second OBTAIN/View command moves the cursor to the next view record
associated with DNO value 101 or the next highest DNO value. If the cursor is moved to
the next highest DNO value, control is transferred to the DCURSOR label (defined by the
BREAK parameter). Control also branches to the DCURSOR label if the system has
processed all DNO values.
3.   This proc uses OBTAIN/View commands within a transaction to change the
     BUILDING_NO field value in all DEPARTMENT view records.

     Proc Segment:
     START/TRANSACTION PW=DEPARTMENT
     OBTAIN/VIEW DEPARTMENT.DNO,POSITION=FIRST, +
                      1
     INTENT=CURRENT,+
           END=OBT1END,ERR=OBT1ERR
     *
     LOOP:
                                   2
        ASSIGN/FIELD BUILDING_NO=1
                                          3
        PUT/VIEW[@1]DEPARTMENT,ERR=PUTERR
        OBTAIN/VIEW DEPARTMENT.DNO,POSITION=NEXT, +
                             4
           INTENT=CURRENT,+
           END=DCURSOR,ERR=OBT2ERR
     JUMP LOOP
     *
     DCURSOR:
        FINISH/TRANSACTION
        DROP/CURSOR CURSOR=1
        RETURN
     *




                                                              Command References  367
                   OBT1END:
                      SHOW/MESSAGE !DMSTAT!
                      TELL '(THE INDEX IS EMPTY)'
                      ABORT/TRANSACTION
                      RETURN
                   *
                   OBT1ERR:
                      SHOW/MESSAGE !DMSTAT!
                      TELL '(THE INDEX MIGHT NOT EXIST)'
                      ABORT/TRANSACTION
                      RETURN
                   *
                   OBT2ERR:
                      SHOW/MESSAGE !DMSTAT!
                      TELL '(THE CURSOR STOPPED NEAR THIS POSITION)'
                      TYPE DNO,BUFFER=A,LABEL=NO
                      ABORT/TRANSACTION
                      RETURN

                   1
                       The first OBTAIN/View command established the cursor (default cursor number
               1) using the “obtain by position” method. The cursor accesses the first view record
               associated with the lowest DNO value in the index and stores the record in the default
               user buffer A. (If no values are found in the index, control branches to the OBT1END
               label.)
                   2
                       The ASSIGN/Field assigns a new value to the BUILDING_NO field.
                   3
                     The PUT/View command uses an obtain cursor reference [@1] to put the changed
               view record into the database.
                   4
                      The second OBTAIN/View command moves the cursor to the next view record
               associated with the lowest DNO value or the first view record associated with the next
               highest DNO values in the index. When the system reaches the end of the index, control
               branches to the DCURSOR label defined by the END parameter.




368  Command References
              OPen/DB
Purpose:

              To open a database via a User Data Model. The User Data Model defines the view types
              that can be used with the database. The last User Data Model opened is considered the
              default database and model. To see what databases are open, use the SHow/DB
              command. To close an existing database, use the CLOse/DB command. To switch the
              default to another open database, use the SET/DEFault command.

Syntax:

              OPen {/DB} model
                      {,CHEckref=YES | NO}
                      {,ERR=errlabel}
                      {,INTENT=USER | READ | UPDATE | EXCLUSIVE}
                      {,JOUrnal=YES | NO}
                      {,RECovery=YES | NO}
                      {,VALidate=YES | NO}
                      {,VERsion=dbversion}
                      {,WAIt=YES | NO}

Parameters:

              model                                                                          (Required)

              Identifies the Database and User Data Model in one of the following formats:

                    <database.model>
                    database.model

              There can be as many as 30 databases open at one time on an UNIX or VMS system.

              /DB                                                                             (Optional)

              Optional qualifier for the OPen command.

              CHEckref=YES | NO                                                               (Optional)

              Indicates whether the referential constraints defined for the database are performed. The
              default is YES.

              ERR=errlabel                                                                    (Optional)




                                                                           Command References  369
               Indicates the label within a command procedure to branch to if the OPen/DB command
               results in an error.

               INTENT=USER | READ | UPDATE | EXCLUSIVE                                        (Optional)

               Indicates how the database will be used.


               USER               The intent is based on the user‟s privileges and the database
                                  privileges. If possible, the database is opened with UPDATE intent.
                                  Otherwise, the database is opened with READ intent.

               READ               The database can only be searched. No changes are possible.

               UPDATE             Changes can be made to the database.

               EXCLUSIVE          Changes can be made to the database and no other user can have the
                                  database open.

               Unless a SET/DEFaults command overrides the value for INTENT, the default is USER.

               JOUrnal=YES | NO                                                               (Optional)

               Indicates whether journal processing is performed. The default is YES.


               YES      Journal processing is performed.

               NO       Journal processing is not performed.

               RECovery=YES | NO                                                              (Optional)

               Indicates whether automatic recovery is enabled in case of a system failure. The default
               is YES.


               YES      Automatic recovery is enabled.

               NO       Automatic recovery is not enabled.

               If RECovery=NO, you must also enter INTENT=EXCLUSIVE. If a system failure
               occurs, the database is marked unusable and the UID of the user who disabled recovery is
               written to the Kernel‟s output file and log file.



370  Command References
              VALidate=YES | NO                                                                   (Optional)

              Indicates whether field validity checks are performed. The default is YES.

              VERsion=dbversion                                                                   (Optional)

              Indicates the version number of the database to open. You can open more than one
              version of a database, but you must use different models. The dbversion is a number from
              0 to 99. If not specified, version 0 is opened.

              WAIt=YES | NO

              Indicates whether the system waits for the database when it is locked by another user.
              Unless a SET/DEFaults command sets WAIt to NO, the default is YES.


              YES       The system waits for the database, when locked by another user, to become
                        available. This can cause the system to idle for quite some time.

              NO        The system does not wait for the database, when locked by another user, to
                        become available.


Prompts:
                   database.model:
                   Change defaults (Y/N)? >

Key Points:
                  Only UPDATE and EXCLUSIVE intents allow changes to be made to the database.
                   EXCLUSIVE intent is used to prevent other users from having the database open.
                  USER intent is used to let READ or UPDATE intent be determined based on the
                   user‟s privileges and the database privileges.
                  The CHEckref, JOUrnal, RECovery, and VALidate parameters control the types of
                   backup information kept, and the checks made on changed data.
                  The RECovery parameter indicates whether automatic recovery is enabled in case of
                   a system failure. When RECovery=YES, the system uses a transaction work file to
                   keep changes made to the database in synchronization. Contents of the transaction
                   work file are used to return the database to the state that existed just prior to a system
                   failure.
                  When RECovery=NO, the system is not slowed down by having to record
                   transactions in the transaction work file. If there is a system failure, recovery is not
                   possible without a new database backup. If a system failure occurs, the database is
                   marked unusable and the UID of the user who disabled recovery is written to the



                                                                               Command References  371
                    Kernel‟s output file and log file. RECovery=NO should be used only when a large
                    volume of data is being added to the database in batch mode and the database will be
                    backed up at the end of the job. INTENT must be EXCLUSIVE when
                    RECovery=NO.

Examples:

               Note: The actual output of the commands in the examples below may vary depending
               on the operating system and/or the version of BASIS that you are using.
               1.   You can open a database by entering Open/DB and responding to prompts (a.) or by
                    entering the name of the database with the command (b.). Commands in this example
                    use the default values for the optional OPen/DB parameters.
               a.   FQM> OPEN/DB
                    database.model: TOUR.ALL
                    Change defaults (N/Y)? > N

               b.   FQM> OPEN/DB TOUR.ALL

               2.   Values for the OPen/DB command parameters can be set by changing defaults. For
                    additional information about each parameter, you can enter ? as your response to a
                    prompt.
                    FQM> OPEN/DB
                    database.model: TOUR.ALL
                    Change defaults (Y/N)? > Y
                    INTENT= ?
                    The INTENT parameter shows how you want to use the database.
                        'USER'      - Opens the database with whichever intent
                                      (READ or UPDATE) you are allowed.
                        'UPDATE'    - Lets you make changes to the database.
                        'READ'      - The database can only be read.
                        'EXCLUSIVE' - You can update the database while excluding
                                      other users from opening it.
                    NOTE: The default is the value of the SET/Default parameter
                          INTENT, which is initially 'USER' for FQM and 'READ' for RW.
                    INTENT= READ
                    WAIT= ?
                    The WAIT parameter tells BASIS whether to wait for a locked
                    database. The default is the value of the SET/Default parameter
                    WAIT, which is initially 'YES'.
                    WAIT= NO
                    ERR=
                    VERsion=
                    CHEckref=
                    VALidate=
                    JOUrnal=
                    RECovery=

               3.   You can enter values for parameters with the OPen/DB command. The following
                    command opens the ALL model of the TOUR database. It indicates that the intent is
                    read only and that the user does not want to wait for the database to become available
                    if it is locked.




372  Command References
     FQM> OPEN/DB TOUR.ALL,INTENT=READ,WAIT=NO

4.   You cannot open a database.model that is already open. Use SHOW/DB to see what
     databases are open. If you close the database.model, you can, of course, use the
     OPen/DB command to open it again. You can open several different models of the
     same database. The /DB qualifier is optional. The OPen and OPen/DB commands
     are equivalent.
     FQM> OP/DB TOUR.ALL
     USER ERROR( 652). The database is already open.
5.   The system cannot find the nonexistent FQMC User Data Model requested for the
     TOUR database. Without entering a valid User Data Model name, you cannot open a
     database.
     FQM> OPEN/DB TOUR.FQMC
     USER ERROR( 802). The database model does not exist.
6.   The TOUR.ALL model is opened using the default INTENT=USER and the user has
     the UPDATE privilege for the database model. The ACME0.FQMA model is
     opened using INTENT=READ. Notice that the last model opened becomes the
     default database and model.
     FQM> OPEN/DB TOUR.ALL
     FQM> SHOW/DB
     The open database models are:
     Intent   Version Database.Model     Kernel               Primary Name
     ------   ------- --------------     ------               ------------
     Update      0     <TOUR.ALL>        DMKA1                TOUR    (default)
     FQM> OPEN/DB ACME0.FQMA,INTENT=READ
     FQM> SHOW/DB
     The open database models are:

     Intent     Version     Database.Model         Kernel     Primary Name
     ------     -------     --------------         ------     ------------
     Update        0        <TOUR.ALL>             DMKA1      TOUR
     Read          0        <ACME0.FQMA>           DMKA1      ACME0   (default)




                                                            Command References  373
               OPen/File
Purpose:

               To open a sequential file for use as an input file, an output file, or an update (appended)
               file.

Syntax:

               OPen/File {FILE= | FD=} filedescriptor, FID=identifier,
                       INTENT=UPDATE | READ | WRITE
                       {,CARriage=NO | YES}
                       {,CREATE=NO | YES}
                       {,ERR=errlabel}
                       {,LINE=1 | integer}
                       {,PAGE=1 | integer}
                       {,PAGE_LENgth=0 | integer}
                       {,RAISE=NO | YES}
                       {,RECORDLC=255 | 1:4096}
                       {,RECORDTYPE=VAR | FIX}
                       {,REWIND=YES | NO}
                       {,WAIt=NO | YES}

Parameters:

               filedescriptor                                                                    (Required)

               Specifies the name of the file to be opened.

               FID=identifier                                                                    (Required)

               A 1 to 12 character name that identifies the open file.




374  Command References
INTENT=UPDATE | READ | WRITE                                                        (Required)

Indicates how the file is opened.


UPDATE           The file is opened at the end of information for writing. New data is
                 appended to the end of the file. Other users cannot open the same file.

READ             The file is opened for shared reading. Other users can open and read the
                 same file.

WRITE            The file is opened for writing. If the file contains old data, it is
                 overwritten by new data. Other users cannot open the same file.

CARriage=NO | YES                                                                   (Optional)

Indicates whether the first character of each record is a carriage control character. The
default is NO.


NO         The first character is data. Carriage control characters are not used.

YES        The first character is a carriage control character.

CREATE=NO | YES                                                                     (Optional)

Indicates if a new file is created.


NO         The file must already exist. If CREATE is not specified and
           INTENT=WRITE, CREATE=YES will be used. If INTENT=UPDATE or
           INTENT=READ, CREATE=NO will be used.

YES        The file must not exist. It is created by the OPEN/FILE command.




                                                                  Command References  375
               ERR=errlabel                                                                      (Optional)

               Specifies the label in the proc to branch to if the OPEN/FILE command fails.

               Note: If any of the specified term IDs are not in the result set, the system considers this
               to be a syntax error because it is caught during the parsing stage. Therefore, the system
               will not branch to the label indicated by the ERR parameter, which handles execution
               errors only. In the event of syntax errors, you can have the system transfer control to a
               label indicated by the ON/SYNTAX command.

               LINE=1 | integer                                                                  (Optional)

               Indicates the value of the starting line count. This value must be a legal non-negative
               integer. This parameter is ignored if PAGE_LENGTH=0. The default is 1. This
               parameter is for migration only.

               PAGE=1 | integer                                                                  (Optional)

               Indicates the value of the starting page count. This value must be a legal non-negative
               integer. This parameter is ignored if PAGE_LENGTH=0. The default is 1. This
               parameter is for migration only.

               PAGE_LENgth=0 | integer                                                           (Optional)

               Determines whether the file‟s paging mode will be non-paged (PAGE_LENGTH=0) or
               paged (PAGE_LENGTH>0). If PAGE_LENGTH=0, the PAGE and LINE parameters
               are ignored. The default is 0. This parameter is for migration only.

               RAISE=NO | YES                                                                    (Optional)

               Indicates whether lowercase letters are translated into uppercase letters. The default is
               NO.


               NO           Lowercase letters are not translated.

               YES          Lowercase letters are translated into uppercase letters upon input and
                            output.

               RECORDLC=255 | 1:4096                                                             (Optional)

               Specifies the record length in characters. You can use 1 to 4096 characters. The default
               is 255 characters.




376  Command References
RECORDTYPE=VAR | FIX                                                               (Optional)

Indicates whether the file‟s records are of variable or fixed character length. The default
is VAR.


VAR          Each record is of varying character length. The RECORDLC parameter
             determines the maximum character length of a record.

FIX          Each record is of fixed character length. The RECORDLC parameter
             determines the character length of each record.

REWIND=YES | NO                                                                    (Optional)

Indicates whether the file‟s record pointer is positioned to the first record. The default is
YES.


YES          The file‟s record pointer is positioned to the first record.

NO           The file‟s record pointer remains at its current position.




                                                                 Command References  377
               WAIt=NO | YES                                                                     (Optional)

               Indicates whether the system waits for a file that is currently accessed by another user and
               cannot be shared. The default is NO.


               NO           The system does not wait until the file is available. The message “File is
                            busy - it is not available to this job” is issued.

               YES          The system waits until the file is available. The message “...waiting for file:
                            <filename>” is issued. This can cause the system to idle for quite some
                            time.


Prompts:
                    FILE=
                    FID=
                    INTENT=
                    Change defaults (Y/N)? >

Key Points:
                   You can have up to 8 files open at one time.
                   Before you can read from or write to a sequential file, you must use the OPEN/FILE
                    command to open the file. The FID parameter of the OPEN/FILE command assigns
                    a file identifier (FID) to the file. You must supply the FID with subsequent
                    GET/FILE, PUT/FILE, etc., commands.
                   Note that when you open a file with INTENT=WRITE, the OPEN/FILE parameter
                    CREATE=YES is used by default. This means a new file is created. If an existing
                    file is to be read and/or written to, you must specify CREATE=NO with the
                    OPEN/FILE command.
                   The REWIND parameter specifies whether the system must adjust the file‟s record
                    pointer. If REWIND=YES, the system sets the record pointer to the first record in
                    the file. If REWIND=NO, the record pointer will stay at its current position. (On
                    most host systems, the current position is the first record.)




378  Command References
Examples:
            1.   You can open a file only once. To change the INTENT and other parameters, you
                 must close the file and open it again, using the new parameters.
                 FQM> OPEN/FILE FORMATS,FID=A,INTENT=WRITE
                 USER ERROR( 7114). The file identifier specified is already in
                 use.
                 FQM>
            2.   The file named UPDATE1 is currently in use. The system assumes the default
                 WAIT=NO for this OPEN/FILE command.
                 FQM> OPEN/FILE UPDATE1,FID=C,INTENT=UPDATE,CREATE=NO
                 File is busy - it is not available to this job
                 FQM>
            3.   You cannot create a new file if the OPEN/FILE command specifies that you intend to
                 do nothing more than read the file (INTENT=READ). To create a file, you must use
                 the parameters INTENT=WRITE and CREATE=YES.
                 FQM> OPEN/FILE UPDATE1,FID=B,INTENT=READ,CREATE=YES
                 USER ERROR(   30). You are trying to OPEN (CREATE) a new file
                 but you are in READ ONLY mode.
                 FQM>
            4.   The file identifier must be a 1 to 12 character string, not numeric. You cannot open a
                 file that does not exist, unless CREATE=YES. The OPEN/FILE command in this
                 example uses the default parameter CREATE=NO.
                 FQM> OPEN/FILE DATE
                 FID= 1
                 USER ERROR (7005). Illegal value for the OPen/File parameter
                 FID.
                 FID= DT
                 INTENT= READ
                 Change defaults (Y/N)? > N
                 File is absent - it does not exist in the system
                 FQM>




                                                                          Command References  379
               PUT/File
Purpose:

               To write data to an open sequential file. The file must be open with an intent of WRITE
               or UPDATE.

Syntax:

               PUT/File datalist, FID=identifier {, ERR=errlabel}

Parameters:

               datalist                                                                          (Required)

               Contains data item(s) to be written to the file, control items that determine placement of
               data items in the file, and graphic items that enhance the display of data items.

               The items are listed in the datalist in the format: item{,item}

                   A control item can be:


                    $Tn            (begins the data item in column n)

                    $Xn            (moves n columns to the right before beginning the data item)

                    $B             (starts the data item on a new record)

                    $Sn            (leaves n-1 blank records before beginning the data item)

                    $P             (starts the next record with a form feed or carriage control page eject
                                   in column 1)

                    $BELL          (sounds a bell)




380  Command References
Graphic items provide a value with one or more of the following attributes:
intensity, underline, reverse, or blink. The syntax of a graphic item is:

    $G{/attribute}0:4

The specific graphic attributes remain in effect until either a $G is specified without
any attributes (to turn off all graphics) or a $G with different attributes is supplied (to
change the attributes).

A data item can be a character, integer or real constant, a proc or global variable, or
an expression. A picture may be appended to a data item to affect its format in the
file. The syntax for specifying a picture is:

item:{just}size{/qualifier}{just}

just :        <|>
    <<        left justified

    >>        right justified

    <>        center value in column

    ><        squeeze the value. The value should only occupy as much space as
              needed, up to the column width.



size :        w          for integer values, w(1:80) specifies the width of the column.

              x          for character values, x(1: 4096) specifies the width of the
                         column.

              w.d        for numeric values to be displayed with decimal points,
                         w(1:80) specifies the width of the column and d(0:40)
                         specifies the number of digits after the decimal point.



qualifiers:              The picture qualifiers specify how to edit the value. They are
                         grouped in categories. The * indicates the default.




                                                            Command References  381
                  Fill group:
                   */B          leading blank fill

                    /Z          leading zero fill

                    /S          leading star fill

                  Sign group:
                    /CR         Print CR at right of value if it is negative.

                    /DB         Print DB at right of value if it is negative.

                    /TN         Trailing negative (print - to the right of negative values)
                                */LN leading negative (print - to the left of negative values)
                                 /LS leading sign (print + or - to the left of the value)

                    /TS         Trailing sign (print + or - to the right of the value).

                    /PN         Parenthesize negative.

                    /TSO        Trailing sign overpunch.

                    /LSO        Leading sign overpunch.

                  Base Group:
                   */D          decimal

                    /H          hexadecimal

                    /O          octal




382  Command References
               Others:
                 /E          Print the number using scientific notation.

                 /NE         Do not use scientific notation.

                 /NP         Do not print the H# or O# base prefix.

                 /C          Insert commas to the left of each group of three digits.

                 /M          Integer is money so insert a point to the left of the last two digits.

                 /BZ         Print blanks if value is zero.

                 /DC         Drifting currency symbol.

                 /DATEf      Print date in a specified standard format. f must be an integer code for
                             the date type (*/DATE21).

                             If a data item has no picture, the system displays it in the smallest
                             possible space.


           FID=identifier                                                                     (Required)

           A 1- to 12- character name used to identify an open file. An asterisk (*) indicates that
           data is displayed on the terminal.

           ERR=errlabel                                                                        (Optional)

           Specifies the label in the proc to branch to if the PUT/File command fails.

           Note: If any of the specified term IDs are not in the result set, the system considers this
           to be a syntax error because it is caught during the parsing stage. Therefore, the system
           will not branch to the label indicated by the ERR parameter, which handles execution
           errors only. In the event of syntax errors, you can have the system transfer control to a
           label indicated by the ON/SYNTAX command.

Prompts:
               datalist:
               FID=
               Change defaults (Y/N)? >




                                                                           Command References  383
Key Points:
                   Before data can be written to a sequential file, the file must be opened using the
                    OPen/File command with INTENT=WRITE or INTENT=UPDATE. The FID
                    parameter of the OPen/File commands assigns a file identifier (FID) to the file. You
                    must specify the FID in subsequent GET/File, PUT/File, etc. commands.
                   When you open a file with INTENT=WRITE or INTENT=UPDATE, the system
                    assumes the OPen/File parameter CREATE=YES by default. This means a new file
                    is created. If you want to read or write to an existing file, you must use
                    CREATE=NO with the OPen/File command.
                   If records already exist in the file, the system adjusts the file‟s record pointer based
                    on the REWIND parameter of the OPen/File command. If you update an existing file
                    with REWIND=NO, the PUT/File command adds new data to the end of the file. If
                    REWIND=YES, the PUT/File command overwrites existing data.

Examples:
               1.   You must open a file with INTENT=WRITE or INTENT=UPDATE before you
                    execute the PUT/File command.
                    FQM> OPEN/FILE SAL101,FID=C,INTENT=READ
                    FQM> PUT/F 1235,FID=C
                    USER ERROR( 62). Invalid Request. User tried to read a
                    sequential file that was opened for write or tried to write on
                    a sequential file that was opened for reading.
                    FQM>
               2.   The system cannot execute a PUT/File command until you have opened the specified
                    file. The SHOW/FID command displays the open files and the corresponding file
                    identifiers.
                    FQM> PUT/FILE EMP,FID=D
                    USER ERROR( 7116). Undefined file identifier.
                    FQM> SHOW/FID
                    FID         File Descriptor
                    ---         ---------------
                    C           sal101
                    SALINCR     salincr
                    FQM>




384  Command References
3.   This example shows how you can use control items and graphic items with the
     PUT/File command to specify the format in which data is stored and displayed.
     FQM> SET/PV CUSTNO= '1201A'
     FQM> SET/PV NAME = 'JOHN Q. SMITH'
     FQM> SET/PV STREET = '2601 WARING ST.'
     FQM> SET/PV CITY = 'BERKELEY'
     FQM> SET/PV STATE = 'CA'
     FQM> SET/PV ZIP = '94720
     FQM> OPEN/FILE MAIL,FID=Z,INTENT=WRITE,RECORDLC=25
                                                           1
     FQM> PUT/FILE FID=Z,$S2,$T19,$G/U,CUSTNO,$G,$B,$T2, +
     ...NAME,$B,$T2,STREET,$B,$T2,CITY,',',$X,STATE,$X, ZIP,$P
     FQM> CLOSE/FILE FID=Z

     FQM> SHOW/FILE MAIL,HEADER=NO

              1201A

     JOHN Q. SMITH
     2601 WARING ST.
     BERKELEY, CA 94720

     1
      Control items like $X, $B, and $P determine the placement of data items in the file.
The graphic items, $G/U and $G, delimit data items to be printed or displayed with the
underline enhancement.
4.   This example shows how to use the OPen/File, SET/PV, and PUT/File commands to
     append data to the end of an existing file.
     FQM> SHOW/FILE SAL101,HEADER=NO
     Name                       Sal/Month                        Com/Month
     --------------             -----------                      -----------
     TODD, FAY                  $1,053.00
     SARCHIN, TONY              $1,395.00                        $432.00
     KELLY, CINDY               $2,713.00
     ROBINSON, JOHN             $2,629.00
     DOE, ABRAHAM               $1,050.00
     LEWIS, BILL                $1,200.00
     BODNARUK, ANN                $811.00
     WILLIAMS, JAMES            $2,500.00
     PETERS, BRENDA             $1,250.00
     LYONS, JEANNE              $1,300.00
     ANGELLO, LUKE              $1,477.00
     SCHAUER, RACHEL            $1,378,00




                                                             Command References  385
                                                                                  1
                   FQM> OPEN/FILE SAL101,FID=SAL,INTENT=UPDATE
                                                                                           2
                   FQM> SET/PV FIGTEXT='Figure 3: File created by +
                   ... TYPE command.'
                                              3
                   FQM> PUT/F FIGTEXT,FID=SAL
                   FQM> CLOSE/FILE FID=SAL
                   FQM> SHOW/FILE SAL101,HEADER=NO

                   Name                                   Sal/Month                   Com/Month
                   --------------                         -----------                 -----------
                   TODD, FAY                              $1,053.00
                   SARCHIN, TONY                          $1,395.00                   $432.00
                   KELLY, CINDY                           $2,713.00
                   ROBINSON, JOHN                         $2,629.00
                   DOE, ABRAHAM                           $1,050.00
                   LEWIS, BILL                            $1,200.00
                   BODNARUK, ANN                            $811.00
                   WILLIAMS, JAMES                        $2,500.00
                   PETERS, BRENDA                         $1,250.00
                   LYONS, JEANNE                          $1,300.00
                   ANGELLO, LUKE                          $1,477.00
                   SCHAUER, RACHEL                        $1,378,00
                                                                              4
                   Figure 3: File created by              TYPE command.
                   FQM>

                   1
                    To add information to the contents of an existing file, you must open that file with
               INTENT=UPDATE (supplied) and REWIND=NO (default).
                   2
                      The SET/PV command stores the information to be written to the file in a proc
               variable.
                   3
                       The PUT/File command specifies this proc variable as a datalist.
                   4
                       Note that the new data appears at the end of the file's contents.




386  Command References
              PUT/View                                                           (FQM only)
Purpose:

              To copy a changed view record from a user buffer into a database.

Syntax:

              PUT{/View} viewbuf_ref
                     {,ERR=errlabel}
                     {,ROLLBACK=rlabel}
                     {,WAIt=YES | NO}

Parameters:

              viewbuf_ref                                                                     (Required)

              Specifies the view record to be changed (or created) and the user buffer that temporarily
              stores the new record. The viewbuf_ref must be in the form reference_spec
              view_id{@user_buffer_name}.

              ERR=errlabel                                                                     (Optional)

              Specifies the label in the proc to branch to if the PUT/View command fails.

              Note: If any of the specified term IDs are not in the result set, the system considers this
              to be a syntax error because it is caught during the parsing stage. Therefore, the system
              will not branch to the label indicated by the ERR parameter, which handles execution
              errors only. In the event of syntax errors, you can have the system transfer control to a
              label indicated by the ON/SYNTAX command.

              ROLLBACK=rlabel                                                                  (Optional)

              Specifies the label in the proc to branch to if the PUT/View command is rolled back in a
              deadlock situation.




                                                                            Command References  387
               WAIt=YES | NO                                                                    (Optional)

               Indicates whether the system waits for locked resources. The default is YES.


               YES         The system waits for locked resources to become available.

               NO          The system does not wait for locked resources to become available. When a
                           lock occurs, the command fails and DMSTAT is set to 867.


Prompts:
                    viewbuf_ref:
                    Change defaults (Y/N)? >

Key Points:
                   To specify which record is to be replaced by the contents of the user buffer, use one
                    of these identifiers:

                    A unique key.
                    A result set member reference.
                    A cursor established by the OBTAIN/View command.
                   You can use the PUT/View command only within a transaction (after a
                    START/TRANsaction command and before a FINISH/TRANsaction or
                    ABORT/TRANsaction command).
                   The PUT/View command checks the values of those fields in the user buffer that are
                    changed. If these values violate the integrity constraints defined by the DBA, the
                    system cannot execute the PUT/View command.
                   If a view record with the specified unique key already exists in the database, the
                    PUT/View command replaces it with the new record. If a record with the specified
                    unique key does not exist in the database, the PUT/View command adds a new
                    record.

Examples:
               1.   You can use a unique key reference to put an individual view record into the
                    database. This example also shows how the system handles a violated integrity
                    constraint and one way to resolve the problem.
                    FQM>   START/TRANSACTION PW=DEPARTMENT
                    FQM>   GET/VIEW [DNO=201]DEPARTMENT@B
                    FQM>   ASSIGN/FIELD BUILDING_NO@B = 11
                    FQM>   PUT/VIEW [DNO=201]DEPARTMENT@B
                    USER   ERROR( 860).



388  Command References
                                                                      1
     Data conversion error or data validation error.
     FQM> ACQUIRE/PV ERRORCOUNT N1=ERRCNT
     FQM> SHOW/PV ERRCNT
          ERRCNT = 1
                                                                          2
     FQM> ACQUIRE/PV ERRORREF 1,N1=ERRCODE,C1=ERRELEM
     FQM> TELL 'UE !ERRCODE! THE !ERRELEM! HAS +
        . . . AN INCORRECT VALUE'
     UE 1303 THE BUILDING_NO HAS AN INCORRECT VALUE

     1
     If the values in the changed view record violate integrity constraints, the
PUT/View command fails.
     2
    You can use the ERRORCOUNT and ERRORREF options of the ACQuire/GV or
ACQuire/PV command to determine which field contains an illegal value.
2.   This example shows how to use the FIND command with the PUT/View command to
     process the members of a result set. This proc segment uses a PUT/View command
     in a loop to change the telephone number of each member in the result set.

     Proc Segment:
     FIND EMPLOYEE WHERE DNO=201 END,RESULT=NO
     ACQUIRE/PV MEMBERS N1=MEMTOT
     *
     TRYAGAIN:
     SET/PV M=0
     START/TRANSACTION SW=EMPLOYEE
     *
     LOOP
        SET/PV M=M+1
        JUMP_IF (M GT MEMTOT),COMMIT
        GET/VIEW[0,!M!]EMPLOYEE@B,WAIT=YES,ERR=GETERR, +
                             1
           ROLLBACK=TRYAGAIN
        ASSIGN/FIELD TEL@B = 1405
        PUT/VIEW[0,!M!]EMPLOYEE@B,WAIT=YES,ERR=PUTERR, +
           ROLLBACK=TRYAGAIN
     END_LOOP
     *
     COMMIT:
        FINISH/TRANSACTION
        RETURN
     *




                                                              Command References  389
                    PUTERR:
                       SHOW/MESSAGE !DMSTAT!
                       TELL 'THE PUT/VIEW command was unsuccessful.'
                       ABORT/TRANSACTION
                       RETURN
                          :
                          :

                    1
                      The PUT/View command uses the result set reference [0,!M!] to access each
               member (!M!) of the last result set formed (0). The parameter WAIT=YES specifies that
               the system waits for the view record to become available if it is locked by another user.
               The parameter ROLLBACK=TRYAGAIN tells the system to pass control to the
               TRYAGAIN label if the transaction is aborted due to a deadlock situation.
               3.   In this example, the OBTAIN/View command uses an indexed field value to locate a
                    view record. The PUT/View command then uses the obtain cursor to process the
                    associated record.

                    Proc Segment:
                    START/TRANSACTION PW=EMPLOYEE
                    OBTAIN/VIEW    +
                       EMPLOYEE.DNO@B='101',INTENT='CURRENT',END=OBT1END, +
                                   1
                       ERR=OBTERR
                    *
                    LOOP
                       ASSIGN/FIELD MGR_NO@B='5519'
                                                          2
                       PUT/VIEW [@1]EMPLOYEE@B,ERR=PUTERR
                       OBTAIN/VIEW
                       EMPLOYEE.DNO@B,POSITION='NEXT',INTENT='CURRENT', +
                       BREAK=DCURSOR,END=DCURSOR,ERR=OBT2ERR
                    END_LOOP
                    *
                    DCURSOR: DROP/CURSOR CURSOR=1
                    FINISH/TRANSACTION
                    *
                    *PUTERR:
                       SHOW/MESSAGE !DMSTAT!
                       ABORT/TRANSACTION
                       RETURN
                       :
                       :

                    1
                        The OBTAIN/View command establishes a cursor numbered 1.
                    2
                     The PUT/View command uses the obtain cursor reference ([@1]) to indicate the
               view record occurrence. The ERR=PUTERR parameter indicates that control branches to
               the PUTERR label if the PUT/View command fails.




390  Command References
              RANk
Purpose:

              To display the unique values for a field in order of frequency and display the frequency of
              each value from a result set. The $COUnt, $MAXimum, $MEAn, $MINimum, and
              $TOTal functions can be used with the RANk command if the result set was sorted by the
              rank field. Other group summary commands are TALly and COUnt.

Syntax:

              RANk field_id {(subscript)} {[startchar:{endchar}]}
                     {,ABSent='absstrg'}
                     {,APPend=YES | NO}
                     {,ERR=errlabel}
                     {,FID=fid}
                     {,FILE | FD=filedescriptor}
                     {,FREQuency=YES | NO}
                     {,function(expr)}0:20}
                     {,LABel=YES | NO}
                     {,MEMbers=* | member}
                     {,QREAD=NO | YES}
                     {,SET=0 | setnumber}
                     {,SKIP=1 | 0:100}
                     {,SORTed=YES | NO }
                     {,SPAcing=2 | 0:15}
                     {,TRUncated='trstrg'}
                     {,WAIt=NO | YES}
                     {,WIDth=80 | 1:512}
                     {,WRAp=YES | NO}

Parameters:

              field_id                                                                         (Required)

              Indicates a field whose unique values are displayed. The result set must be ordered by
              this field if SORTed is set to YES. The field must have been ordered by the FInd
              command which produced the result set, or it must be ordered by this command with the
              SORTed=NO parameter. If SORTed=NO, the sort will take place before the RANk. An
              optional picture format can be specified for the field if desired. This is the same picture
              format used by the TYpe command.




                                                                            Command References  391
               The following two optional qualifiers for the field_id enable the RANk command to work
               for compound fields or a portion of a character field:


               (subscript)                 Ranks and displays the unique values for the subfield
                                           identified by the subscript.

               [startchar:{endchar}]       Ranks and displays the unique values for the portion of the
                                           field specified by a beginning character position or for a range
                                           from a beginning character position through an ending
                                           character position.

               ABSent='absstrg'                                                                    (Optional)

               Indicates the 1 to 15 character string displayed when a field value is absent from a view
               record. The default is ' '.

               APPend=YES | NO                                                                     (Optional)

               Indicates whether the output is appended to an existing file. If the FILE parameter is not
               entered, the value of this parameter is ignored. The default value is YES.


              YES        The output is appended to an existing file. If the file named by the FILE
                         parameter does not already exist, output is written to the file named by the
                         FILE parameter.

              NO         The output is written to a new file.

               ERR=errlabel                                                                        (Optional)

               Indicates the label in a command procedure to branch to if the RANk command fails.

               FID=fid                                                                             (Optional)

               Indicates the file identifier of the output file used by the RANk command. If used, FID
               must refer to a file previously opened by an OPEN/FILE command.

               FILE | FD= filedescriptor                                                           (Optional)

               Indicates the name of the file the RANk command creates or appends and uses as the
               output file. If not supplied, the default output file (usually displayed to terminal) is used.




392  Command References
FREQuency=YES | NO                                                              (Optional)

Indicates whether the frequency count for each unique value of the RANk field is
displayed. The default is YES.

function(expr)                                                                  (Optional)

The functions $COUnt, $MAXimum, $MEAn, $MINimum, and $TOTal display the
requested information which is calculated for each group of members represented by each
unique value of the RANk field. The expr can be a simple field or an expression. (See
the TYpe command syntax chart in this manual for full details about legal expressions.)
Functions can be specified only when the result set was sorted by the FIND command
(SORTed=YES).

LABel=YES | NO                                                                  (Optional)

Indicates whether labels are used as column headings. The label is a label supplied in a
picture on the RANk command (/'label'), a default label (from SET/PICture or the DDB),
or a derived label (for an expression). The default is YES.

MEMbers=* | member                                                              (Optional)

Indicates which members of a result set are ranked. Member is in one of the following
formats. The default is all (*).


*        All members are ranked.

m:n      Members m through n are ranked.

m:*      Members m through the last member are ranked.

m        Member m is ranked.

(m,m)    Member numbers specified in a list must be enclosed in parentheses and
         separated by commas.

QREAD=NO | YES                                                                  (Optional)

Indicates whether or not records stored in the queue area are included in the ranking. The
default is NO.




                                                             Command References  393
               NO         Only database records are included in the ranking.

               YES        Both queue area and database records are included in the ranking.

               SET=0 | setnumber                                                                   (Optional)

               Indicates the number of the result set ranked. Set number is in one of the following
               formats. The default is the currently active result set (0).


               0         Members of the last active result set are ranked.

               -m        Members of result set number “last active result set minus m” are ranked.

               m         Members of result set number m are ranked.

               SKIP=1 | 0:100                                                                      (Optional)

               Indicates how many lines are skipped between each line of information. The default is 1
               line.

               SORTed=YES | NO                                                                     (Optional)

               Indicates whether the result set is to be sorted on the ranked field. The default is YES. If
               the FInd command did not sort the result set on the field to be ranked by using the
               ORDER BY clause, you must use the SORTed=NO parameter.


                   WARNING: If you fail to specify NO for the SORTed parameter when the result
                   set has not been sorted on the relevant field, then RANK may return an incorrectly
                   ordered list.


               SPAcing=2 | 0:15                                                                    (Optional)

               Indicates how many spaces are displayed between columns where no spacing is specified.
               The value is from 0 to 15. The default value is 2.

               TRUncated='trstrg'                                                                  (Optional)

               Indicates a 1- to 8-character string printed as the last few characters of a data value that
               has more characters than the specified space allows. The default is '...'.




394  Command References
              WAIt=NO | YES                                                                    (Optional)

              Indicates whether the RANk command waits for resources locked by other users to
              become available. The default value is NO.


              NO        The RANk command displays a message indicating that the member is not
                        available. It does not wait.

              YES       The RANk command waits.

              WIDth=80 | 1:512                                                                 (Optional)

              Indicates the character width of a page. The page width can be from 1 to 512 characters.
              The default value is 80.

              WRAp=YES | NO                                                                    (Optional)

              Indicates whether lengthy data wraps to the next display line. The default is YES.


              YES       Lengthy data is wrapped to the next line.

              NO        Only the characters of data that fit within the page width are displayed.


Prompts:
                   field_id:
                   Change defaults (Y/N)? >

Key Points:
                  Rank cannot be used with section-level fields in a sectioned-style document.
                  Rank cannot be used with text stream fields.
                  You can use the $COUnt, $MAXimum, $MEAn, $MINimum, and $TOTal functions
                   to display statistics for other fields for each unique value of the rank field. (See
                   examples 2, 3, and 4.) You can use these functions only when the result set was
                   sorted by the FIND command (SORTed=YES).
                  Many of the RANk command parameters are the same as parameters of the TYpe
                   command. Default values are defined for these parameters by using the
                   SET/TYpe_options command. Current default values can be displayed by using the
                   SHow/TYpe_options command.




                                                                            Command References  395
                   The TALly command displays the same information as the RANk command except
                    the unique values are displayed in sorted order instead of in order of frequency.

Examples:
               1.   You can indicate the rank field in response to a prompt (a.) or with the command (b.).
                    The result set must be ordered by the field to be used as the rank field. These RANk
                    commands report the unique values of the rank field and the number of records in the
                    result set.
               a.   FQM> FIND EMPLOYEE ORDER BY JOB
                         Result set 1 contains 130 members.
                    FQM> RANK
                    field_id: JOB
                    Change defaults (Y/N)? > N

                    Frequency     Job Title
                    ---------     ---------------
                           26     Secretary
                           22     Clerk
                           19     Programmer
                           19     Salesman
                           15     Administrative
                                  Assistant
                             15   Manager
                              8   Operator
                              5   Vice-President
                              1   President
               b.   FQM> FIND EMPLOYEE ORDER BY JOB
                         Result set 2 contains 130 members.
                    FQM> RANK JOB
                    Frequency Job Title
                    --------- ---------------
                           26 Secretary
                           22 Clerk
                           19 Programmer
                           19 Salesman
                           15 Administrative
                               Assistant
                           15 Manager
                            8 Operator
                            5 Vice-President
                            1 President




396  Command References
2.   The RANk command lists the department numbers in order of the most to the least
     number of employees. If the frequency is the same for several departments (101 and
     501, for example), they are listed in the order determined by the ORDER BY
     parameter of the FInd command. The total of the employees‟ salaries is listed for
     each department.
     FQM> FIND EMPLOYEE ORDER BY DNO
          Result set 3 contains 130 members.
     FQM> RANK DNO, $TOTAL(SALARY)
     Frequency Dept    $TOTAL(SALARY)
     --------- ----    ------------------------
            21   301                   35549.00
            20   201                   32501.00
            19   401                   31791.00
            14   601                   25489.00
            13   202                   16017.00
            12   101                   18756.00
            12   501                   20136.00
            10   302                   13536.00
             9   100                   21750.00
3.   The RANk command lists the department numbers in order of the most to the least
     employees. Various statistics are displayed for each department and various picture
     specifications change the defaults for displaying the results. (See the SET/PICture
     command in this manual for more information about picture specifications.)
     FQM> FIND EMPLOYEE
          Result set 4 contains 130 members.
     FQM> RANK DNO, SORT=YES, $TOTAL(SALARY):13.2/DC/C, +
     . . . $MINIMUM(SALARY):13.2/DC/C, +
     . . . $MAXIMUM(SALARY):13.2/DC/C, +
     . . . $MEAN(SALARY):13.2/DC/C
     Frequency Dept $TOTAL        $MINIMUM $MAXIMUM $MEAN (SALARY)
                      (SALARY)    (SALARY) (SALARY)
     --------- ---- ---------- -------- -------- --------------
            21 301    $35,549.00 $867.00    $2,791.00     $1,692.81
            20 201    $32,501.00 $930.00    $2,700.00     $1,625.05
            19 401    $31,791.00 $829.00    $2,739.00     $1,673.21
            14 601    $25,489.00 $757.00    $2,902.00     $1,820.64
            13 202    $16,017.00 $750.00    $2,258.00     $1,232.08
            12 101    $18,756.00 $811.00    $2,713.00     $1,563.00
            12 501    $20,136.00 $933.00    $3,944.00     $1,678.00
            10 302    $13,536.00 $979.00    $2,227.00     $1,353.60
             9 100    $21,750.00 $1,015.00 $8,000.00      $2,416.67




                                                             Command References  397
               4.   This RANk command displays the frequency and average yearly salary and
                    commission for each job type. The $DEFAULT function causes the commission
                    value (if present) or the value zero (if COMM is null) to be added to the salary.
                    Because null values cannot be used in calculations, you should use the $DEFAULT
                    function to specify a substitute value like zero (0) to be used for any null values.
                    FQM> FIND EMPLOYEE ORDER BY JOB
                         Result set 5 contains 130 members.
                    FQM> RANK JOB, $MEAN((SALARY+$DEFAULT(COMM,0))*12) +
                    . . . :15.2/DC/C/'Average Yearly Salary'
                    Frequency    Job Title        Average Yearly
                                                  Salary
                    ---------    --------------- ---------------
                           26    Secretary             $16,359.23
                           22    Clerk                 $12,802.36
                           19    Programmer            $23,230.11
                           19    Salesman              $25,841.05
                           15    Administrative        $14,211.20
                                 Assistant
                           15    Manager               $31,239.20
                            8    Operator              $13,774.50
                            5    Vice-President        $33,187.20
                            1    President             $96,000.00
               5.   The FInd command creates a set of DEPENDENT view records of employees who
                    work in Department 101. The RANk command lists the Department 101‟s employee
                    numbers in order of employees with the most dependents to those with the fewest
                    dependents.
                    FQM> FIND DEPENDENT WHERE DEPENDENT.ENO = EMPLOYEE.ENO +
                    . .. WHERE EMPLOYEE.DNO=101 ORDER BY DEPENDENT.ENO
                              Result set 6 contains 23 members.
                    FQM> RANK ENO
                    Frequency    Enum
                    ---------    -----
                            5    10055
                            5    10090
                            4    10043
                            3    10037
                            3    10053
                            2    10003
                            1    10085
               6.   The FILE parameter of the RANk command causes the output to be written to a
                    sequential file instead of to the terminal.
                    FQM> FIND EMPLOYEE WHERE DNO=101 ORDER BY JOB
                          Result set 7 contains 12 members.
                    FQM> RANK JOB, FILE=RSTATS




398  Command References
             RECall
Purpose:

             To display commands that you entered earlier in the session. You can execute recalled
             commands in their original form, or you can use your host system editor to edit them.

Syntax:

             RECall {/All | /Edit | /Line | /Perform | /Substitute} {command_specifier}

Parameter:

             /All                                                                          (Optional)

             Displays up to 20 BASIS commands that have been entered in the current session. Each
             is displayed with a number. The numbers are assigned in reverse chronological order.
             Thus, the most recently executed command is designated as 1.

             /Edit                                                     (NT and UNIX only) (Optional)

             Places the specified commands(s) in a temporary edit file in the default host system
             editor. You can then edit the command(s). The system executes the command(s) in the
             file when you exit the host system editor.

             /Edit is the default qualifier for the Windows and UNIX operating systems.

             /Line                                                              (VMS only) (Optional)

             Displays the most recently entered command or another command that is designated by a
             command specifier.

             /Line is the default qualifier for the VMS operating system.

             Instead of typing RECall/Line and pressing the [RETURN] key, you can press the [UP] or
             the [CTRL]/[B] keys to display previously entered commands one at a time, starting with
             the most recent and moving backward. Press the [DOWN] key to move forward one
             command at a time for the most recently displayed command. Thus, if the [UP] key
             displays command 3 and you press it again to display command 4, pressing the [DOWN]
             key would display command 3 again.




                                                                            Command References  399
               /Perform                                                                       (Optional)

               Displays and executes the specified command. This qualifier does not permit you to edit
               the command before you execute it.

               /Substitute                                                                    (Optional)

               Displays a prompt for a string to be changed and then prompts for the new version of the
               string. This is the correction mode available with the / command or SET/MODE
               CORRECT=YES.

               command_specifier                                                              (Optional)

               Identifies the command to be displayed.

               You can use the first several characters of a command to identify it. The system displays
               the most recent command that begins with the specified string.

               You can also use a number to identify the command. As you enter commands in a
               session, the system assigns them numbers in reverse chronological order. The most recent
               command is always designated as 1, and the next most recent is 2, and so on.

               When you use the EDIT qualifier, you can supply a list of numbers or a range of numbers.
               You can specify 0 to enter the EDIT mode without entering any commands in the edit file.

               If you do not supply a command_specifier, the system assumes the most recently entered
               command (1).

Prompt:

               None.

Key Points:
                  You can change the host system editor by changing the value of the environment
                   variable DM_EDIT. For more information, see BASIS Reference, “Environment
                   Variables.”
                  When you recall a previous command containing exclamation points, the number of
                   exclamation points will be reduced. For every two consecutive exclamation points
                   occurring in the command, the RECALL command returns one. For instance,
                   suppose you execute the command
                   TELL 'Hi There!!!!'

                   When you do a recall, this command becomes




400  Command References
TELL 'Hi There!!'

If there is an odd number of exclamation points, then the RECALL command reduces
in the same manner as stated above plus it retains the leftover exclamation point. For
instance, the command
TELL 'Hi There!!!!!'

becomes
TELL 'Hi There!!!'

However, if the exclamation points are broken up by a word or words, such as
TELL 'Hi There!!! Bye!'

the RECALL command reduces consecutive pairs of exclamation points to one, and
the first leftover exclamation point becomes part of a variable extending to the first
exclamation point following the intervening word(s). Since RECALL expands the
variable — that is, converts it to its current value, which is null when the variable, as
here, is unintended — the above command would be returned as
TELL 'Hi There!'

and ! BYE! would be considered a variable. Any remaining exclamation points on
the other side of the variable will be reduced according to the usual rules stated
earlier. In another instance, suppose you enter
TELL 'Hi There!!! Bye!!

RECALL would return
TELL 'Hi There!!'

and, again, ! BYE! would be considered a variable.

In the example command, the first two exclamation points are reduced to one. The
remaining one is grouped with the word Bye and the following exclamation point to
form a variable, which is expanded. The last exclamation point is retained in the
command.




                                                           Command References  401
Examples:
               1.   The /All qualifier displays up to 20 of the commands most recently entered in the
                    current session. The system assigns a reference number to each command. (The
                    most recent command is always assigned 1.)
                    FQM> OPEN/DB TOUR.ALL
                    FQM> FIND EMPLOYEE WHERE NAME = 'Smith, John'
                         Result set 1 contains 1 references to 1 members.

                    FQM> FIND EMPLOYEE WHERE JOB = 'Vice-President'
                         Result set 2 contains 5 references to 5 members.

                    FQM> RECALL/ALL
                     1 FIND EMPLOYEE WHERE JOB = 'Vice-President'
                     2 FIND EMPLOYEE WHERE NAME = 'Smith, John'
                     3 OPEN/DB TOUR.ALL
               2.   If you do not supply a command specifier with the RECall command, the system
                    displays the most recently entered commmand. The default RECall command for
                    VMS is RECall/LINE. For all other systems the default RECall command is
                    RECall/EDIT. In this example, the user added AND DNO=101 to the recalled
                    command (FIND EMPLOYEE WHERE JOB = 'Vice-President') and executed the
                    modified command.
                    FQM> FIND EMPLOYEE WHERE JOB='Vice-President' AND DNO=101
                         Result set 3 contains 2 references to 1 members.
               3.   You can use a character string to identify a command to be recalled. (Do not use
                    quotation marks with the string.) The system compares the specified string to the
                    beginning characters of each command until a match is found. Uppercase and
                    lowercase letters make no difference in the search. The system displays only the
                    most recent command that contains the specified string. To recall an earlier
                    command, you can use a more specific string with the RECall command (for
                    example, FIND EMPLOYEE WHERE NAME).
                    FQM> RECALL FIND EMPLOYEE WHERE NAME
                    FQM> FIND EMPLOYEE WHERE NAME = 'Smith, John'
               4.   Use the /PERFORM qualifier if you want to execute the specified command without
                    any changes.
                    FQM> RECALL/PERFORM 2
                    FQM> FIND EMPLOYEE WHERE JOB = 'Vice-President'
                         Result set 4 contains 5 references to 5 members.




402  Command References
5.   The /Substitute qualifier causes the system to prompt you for changes (string
     substitutions) to be made to the recalled command.
     1.   One prompt asks for the string to be changed and another prompt asks for the
          replacement string.
     2.   The system then displays the edited command and prompts you for additional
          changes.
     3.   If you respond “N” (no more corrections to be made), the system executes the
          edited command.
     FQM> FIND EMPLOYEE WHERE JOB='Programmer'
          Result set 1 contains 5 references to 5 members.
     FQM> RECALL/S
          FIND EMPLOYEE WHERE JOB='Programmer'
          Correct the current statement (N/Y)?> Y
          oldstring> 'Programmer'
          newstring> 'Clerk'
          FIND EMPLOYEE WHERE JOB='Clerk'
             1 changes made.
          More corrections (Y/N)> N
     FQM> FIND EMPLOYEE WHERE JOB='Clerk'
          Result set 2 contains 10 references to 19 members.
     FQM>

VMS

6.   RECall/Line is the default RECall command only on VMS. When RECall/Line is
     specified, the last command entered is displayed.
     FQM> RECALL/ALL
      1 FIND EMPLOYEE WHERE         JOB = 'Vice-President'
      2 FIND EMPLOYEE WHERE         JOB = 'Vice-President' AND DNO = 101
      3 FIND EMPLOYEE WHERE         JOB = 'Vice-President'
      4 FIND EMPLOYEE WHERE         NAME = 'Smith, John'
      5 OPEN/DB TOUR.ALL

     FQM> RECALL/LINE
     FQM> FIND EMPLOYEE WHERE JOB='Vice-President'

     You may specify the line to be recalled.
     FQM> RECALL/LINE 2

     FQM> FIND EMPLOYEE WHERE JOB = 'Vice-President' AND +
          DNO=101
     Result set 7 contains 5 references to 5 members.




                                                              Command References  403
               All

               7.    If you want to edit a prior command you must specify RECall/Edit. The /Edit
                     qualifier creates a temporary edit file which contains the commands you specified
                     with the RECall command, in the order in which they were listed. After you exit the
                     editor, the system executes the commands and deletes the edit file.

                     The RECall/Edit command is the default RECall command on all operating systems
                     except VMS.

               Windows, UNIX

                     Commands can be recalled by entering RECALL.

               VMS

                     FQM> RECALL/EDIT 4
                        1    FIND EMPLOYEE WHERE JOB = 'Vice-President'
                     *C
                     [EOB]
                     FIND EMPLOYEE WHERE JOB = 'Vice-President' AND DNO = 401
                     TYPE DNO, ENO, JOB, NAME
                     [EOB]
                     [CTRL]/[Z]
                     *EXIT
                     DEV$DOCDEV:[DOCDEV.PRICE]RECALL_EDIT_OUTPUT.PRC

                     FQM> FIND EMPLOYEE WHERE JOB = 'Vice-President' +
                          AND DNO = 601
                          Result set 8 contains 2 references to 2 members.
                     FQM> TYPE DNO, ENO, JOB, NAME

                     Dept      Enum       Job Title                  Name
                     ----      ----       ---------                  -------------------
                     401       10008      Vice-President             WHANG, BERNARD
                     401       10029      Vice-President             LIN, ANN




404  Command References
              REName/PLibrary
              UNIX, VMS

Purpose:

              To rename a proc in a library file.

              IMPORTANT: The RENAME/PLIBRARY command is not applicable to Windows.

Syntax:

              REName/PLibrary {=any_pri_lib} from_proc_name {TO} to_proc_name

Parameters:

              any_priv_lib                                                                    (Optional)

              Specifies the name of the library containing the proc to be renamed. The default is
              $PRIvate. This may be the name of a specific library or $PRIvate for the private library
              set.

              from_proc_name                                                                 (Required)

              Specifies the name of the proc that you want to rename.

              to_proc_name                                                                   (Required)

              Specifies the new name for the proc.

Prompts:
                     from_proc-name:
                     to_proc_name:
                  Change defaults (Y/N)?             >

Key Points:
                 This command cannot be used to rename a proc in a public library.
                 The proc is not renamed if there is already a proc with the “new” name in the library.




                                                                           Command References  405
Example:

               Rename a proc in a library file.
                   FQM> REN/PL=MENU_LIBRARY GREETING TO INTRO_SCREEN
                   1 library entry(s) renamed.
                   FQM> SHOW/PL=MENU_LIBRARY/DIR INTRO_SCREEN,+
                   ...FULL=YES, HEADER=NO

                   NAME                       Date        Time     Author
                   -----                      -----       -----    -------
                   INTRO_SCREEN               1988 1005   155342   PHILLIPS




406  Command References
              REPLace/View                                                       (FQM only)
Purpose:

              To replace field values in an existing view record.

Syntax:

              REPLace{/View} viewbuf_ref
                     {, ERR=errlabel}
                     {, ROLLBACK=rlabel}
                     {, WAIt=YES | NO}

Parameters:

              viewbuf_ref                                                                     (Required)

              Specifies the view record to be replaced and the user buffer in which the new view record
              is stored. The viewbuf_ref must be in the form reference_spec
              view_id{@user_buffer_name}.

              ERR=errlabel                                                                     (Optional)

              Specifies the label in the proc to branch to if the REPLace/View command fails.

              Note: If any of the specified term IDs are not in the result set, the system considers this
              to be a syntax error because it is caught during the parsing stage. Therefore, the system
              will not branch to the label indicated by the ERR parameter, which handles execution
              errors only. In the event of syntax errors, you can have the system transfer control to a
              label indicated by the ON/SYNTAX command.

              ROLLBACK=rlabel                                                                  (Optional)

              Specifies the label in the proc to branch to if the REPLace/View command is rolled back
              in a deadlock situation.




                                                                            Command References  407
               WAIt=YES | NO                                                                   (Optional)

               Indicates whether the system waits for locked resources. The default is YES.


               YES         The system waits for locked resources to become available.

               NO          The system does not wait for locked resources to become available. When a
                           lock occurs, the command fails and DMSTAT is set to 867.


Prompts:
                    viewbuf_ref:
                    Change defaults (Y/N)? >

Key Points:
                   To access a record, you use one of the following identifiers:

                    A unique key.
                    A result set member reference.
                    A cursor established by the OBTAIN/View command.
                   You can use the REPlace/View command only within a transaction (after a
                    START/TRANsaction command and before a FINISH/TRANsaction or
                    ABORT/TRANsaction command).
                   The REPlace/View command returns a changed view record into a database. The
                    unique key in the user buffer to be replaced into the database must already exist in
                    the database. If the unique key does not already exist in the database, the
                    REPlace/View command fails and the system executes the command(s) specified by
                    the ERR parameter.
                   The REPlace/View command checks the values of those fields in the user buffer that
                    were changed. If these values violate the integrity constraints defined by the DBA,
                    the system does not execute the REPlace/View command.
                   Individual view records are referenced easily by using a unique key reference. (See
                    example 2 below.) By using the FIND command to create a result set, the
                    REPlace/View command and a result set and member reference can be used to
                    change and replace the members of a result set. (See example 2) The
                    OBTAIN/View command can be used to locate a view record via an indexed field
                    value. The OBTAIN cursor can then be used in a REPlace/View command to
                    process the associated view record. (See example 3.)




408  Command References
Examples:
            1.   You can use a unique key reference to replace an individual view record in the
                 database. This example shows how the system handles a violated integrity constraint
                 and one way to resolve the problem.
                 FQM>   START/TRANSACTION PW=DEPARTMENT
                 FQM>   GET/VIEW [DNO=201]DEPARTMENT@B
                 FQM>   ASSIGN/FIELD BUILDING_NO@B=11
                 FQM>   REPLACE/VIEW [DNO=201]DEPARTMENT@B
                 USER   ERROR( 860).
                                                                                  1
                 Data   conversion error or data validation error.

                 Field: BUILDING_NO(1)
                 USER ERROR (1303).
                 The value of the subfield was outside the valid range.
                 FQM> ACQUIRE/PV ERRORCOUNT N1=ERRCNT
                 FQM> SHOW/PV ERRCNT
                    ERRCNT = 1
                                                                 2
                 FQM> ACQUIRE/PV ERRORREF 1,N1=ERRCODE,C1=ERRFLD
                 FQM> TELL 'UE !ERRCODE! THE !ERRFLD! HAS AN +
                 ...INCORRECT VALUE'
                    UE 1303 THE BUILDING_NO HAS AN INCORRECT VALUE

                 1
                 If the values in the changed view record violate integrity constraints, the
            REPlace/View command fails.
                 2
                You can use the ERRORCOUNT and ERRORREF options of the ACQuire/GV or
            ACQuire/PV command to determine which field contains an illegal value.
            2.   This example shows how to use the FIND command with the REPlace/View
                 command to process the members of a result set. This proc segment uses a
                 REPlace/View command in a loop to change the NAME field of each member in a
                 result set. (The proc inserts a blank space between the comma and the first name in
                 the NAME values, which are in LASTNAME, FIRSTNAME format.)




                                                                          Command References  409
                   Proc Segment:
                       FIND EMPLOYEE
                       ACQUIRE/PV MEMBERS M1=MEMTOT
                   *
                   TRYAGAIN:
                      START/TRANSACTION SW=EMPLOYEE
                   *
                   FOR MEM=1, MEMTOT:
                         GET/VIEW [0,!MEM!]EMPLOYEE@B,WAIT=YES,ERR=GETERR, +
                             ROLLBACK=TRYAGAIN
                         ASSIGN/PV NAME = NAME@B
                         INQUIRE/PV LAST, 'ENTER THE NEW LAST NAME FOR +
                             EMPLOYEE ''!NAME!''>'
                         SET/PV LEN=$LC(NAME)
                         SET/PV POS=$MATCH(',',NAME)
                         SET/PV NAME=LAST//NAME[POS:LEN]
                         ASSIGN/FIELD NAME@B ='!NAME!'
                         REPLACE/VIEW [0,!MEM!]EMPLOYEE@B,WAIT=YES, +
                                                           1
                             ERR=REPERR, ROLLBACK=TRYAGAIN
                      END_FOR
                   *
                      FINISH/TRANSACTION
                      RETURN
                   *
                   REPERR:
                      SHOW/MESSAGE !DMSTAT!
                      ABORT/TRANSACTION
                      RETURN
                         :
                         :

                   1
                       The REPlace/View command uses the result set reference [0,!M!] to access each
               member (!M!) of the last result set. The parameter WAIT=YES specifies that the system
               will wait for the view record to become available if it is locked by another user. The
               parameter ROLLBACK=TRYAGAIN tells the system to pass control to the TRYAGAIN
               label if the transaction is aborted due to a deadlock situation.




410  Command References
3.   In this example, the OBTAIN/View command uses an indexed field value to locate a
     view record. The REPlace/View command then uses the obtain cursor to process the
     associated record.

     Proc Segment:
          START/TRANSACTION PROTECTED=CLIENT
          OBTAIN/VIEW CLIENT.CO@B'A NEW LEAF',INTENT='CURRENT', +
                                      1
             END=OBT1END, ERR=OBT1ERR
     *
          LOOP
             ASSIGN/FIELD CNAME@B='NEMMS, EMMA'
                                                  2
             REPLACE/VIEW [@1]CLIENT@B,ERR=REPERR
             OBTAIN/VIEW CLIENT.CO@B,POSITION='NEXT', +
                INTENT=CURRENT,BREAK=DCURSOR,END=DCURSOR, +
                ERR=OBT2ERR
          END_LOOP
     *
     REPERR:
        SHOW/MESSAGE !DMSTAT!
           ABORT/TRANSACTION
           RETURN
     *
     DCURSOR: DROP/CURSOR CURSOR=1
     0   :
        :

     1
         The OBTAIN/View command establishes a cursor numbered 1.
     2
       The REPlace/View command uses the OBTAIN cursor reference ([@1]) to
indicate the view record. The ERR=PUTERR parameter indicates that control branches
to the REPERR label if the PUT/View command fails.




                                                          Command References  411
               RESTore/Set
Purpose:

               To retrieve members of a result set from a stored set file. The stored set file, not a
               printable file, contains the indirect keys for each result set member in a dense internal
               format. To store a result set, you use the STORe/Set command. To see a description of
               the members of a result set in a stored set file, you use the SHow/SF command. To delete
               a stored set, use the DELete/SF command.

Syntax:

               RESTore {/Set} {,FILE | FD=} filedescriptor
                      {,ERR=errlabel}
                      {,INTENT=CURRENT | READ | UPDATE | CHECKOUT}
                      {,RESULT_message=YES | NO}
                      {,TITle=title_var}
                      {,VIEW=view_id_list}
                      {,WAIt=NO | YES}

Parameters:

               FILE | FD=filedescriptor                                                        (Required)

               Names the stored set file containing information for retrieving members of a stored result
               set. You can use either FILE= or FD= to name the parameter.



                Operating system          Filedescriptor

                NT                        Standard Windows file name of the form „disk:\path\name‟. .set
                                          is the default file type.

                UNIX                      Standard UNIX file name of the form '/path/name'. .set is the
                                          default file type.




412  Command References
 Operating system           Filedescriptor

 VMS                        A directory name and/or wildcard characters (*) may be used
                            with the file name. Standard VMS conventions are followed.
                            If the file type is not specified, .SET is used.


SS2

For more information about file_area, see BASIS Reference, “Op. Sys. Specifics” where
Op. Sys. is the name of your operating system.

/Set                                                                             (Optional)

Optional qualifier for RESTore command.

ERR=errlabel                                                                     (Optional)

Indicates the label in a command procedure to branch to if the RESTore/Set command
fails.

INTENT= CURRENT | READ | UPDATE | CHECKOUT                                       (Optional)

Indicates the intent for how the result set is to be used.


CURRENT             The default value for intent.

READ                The result set can be read but not updated.

UPDATE              The result set can be read and updated.

CHECKOUT            The information retrieved is also for update purposes. In addition
                    to the update lock, the view record(s) are marked as checked out in
                    the queue area. Checkout intent can be issued only inside a
                    transaction. This intent is usually used when extended editing is to
                    take place. Once the transaction has been FINISHed, the view
                    record is still “checked out” so that the record will not be updated
                    by others until it has been checked back in.




                                                              Command References  413
               RESULT_message=YES | NO                                                              (Optional)

               Indicates whether a message about the number of members in the result set is to be
               displayed. The default is YES.


               YES     FQM displays a message resembling the following:

                    Result set <title> restored from file:
                    <filedescriptor>
                    Result set # contains x members.



               NO      FQM does not display a message about the restored result set.

               TITle=title_var                                                                      (Optional)

               Indicates the name of a proc variable which is set to the title of the stored result set.

               VIEW=view_id_list                                                                    (Optional)

               Specifies a list of one or more view type identifiers under which to restore the result set
               information. By default, the result set will be restored to the same model and view used
               when the set was stored.

               If RESTore/Set is to restore a set to a different model or view, the view_id_list must
               specify each view that the saved set includes. The specified views must be in the same
               order as specified when the original set was created by the STORe/Set command.

               WAIt=NO | YES                                                                        (Optional)

               Indicates whether the RESTore/Set command waits for resources locked by other users to
               become available. The default value is NO.


               NO       The RESTore/Set command displays a message indicating that the member is
                        not available. It does not wait.

               YES      The RESTore/Set command waits.


Prompts:
                    FILE=
                    Change defaults (Y/N) >




414  Command References
Key Points:
                   The database and model from which the result set came must be open when you enter
                    the RESTore/Set command.
                   A restored set can be used by FQM or Express to highlight the keywords originally
                    used to build the set as long as the record has not been changed since the store.
                   Sets can be restored in a transaction. If a transaction has been started, each member
                    of the restored set is locked with the given intent. The WAit parameter determines
                    whether RESTore/Set waits for locked resources to become available.
                   Because view restrictions are not applied when a result set is restored, you must
                    exercise care in protecting files of stored result sets that contain security-sensitive
                    information. View restrictions are still enforced when the record is accessed.

Examples:
              1.    You must have created a result set and stored it before you can retrieve members
                    using the RESTore/Set command.
                    FQM> FIND CLIENT WHERE COUNTRY='USA'
                          Result set 1 contains 23 references to 23 members.

                    FQM> STORE/SET CLIENT

              2.    You can enter the name of the set you want to restore in answer to a prompt (a.) or
                    you can enter the name with the command (b.).
              a.    FQM> RESTORE/SET
                    FILE= CLIENT
                    Change defaults (N/Y)? > N
                    Result set titled:

              SS1
                    Restored from file: ~Host file descriptor for CLIENT~
                    Result set 2 contains 23 references to 23 members.
              b.    FQM> RESTORE/SET CLIENT
                    Result set titled:

              SS1
                    Restored from file: ~Host file descriptor for CLIENT~
                    Result set 3 contains 23 references to 23 members.
              3.    If the set has been restored in a transaction and the transaction has started, you can
                    use the WAIt parameter to wait for locked resources to become available.
                    FQM> RESTORE/SET DNO101,WAIT=YES




                                                                                Command References  415
               ROUte/File
Purpose:

               To route the specified file for printing.

Syntax:

               ROUte/File {FILE= | FD=} filedescriptor {route_options}

Parameters:

               filedescriptor                                                                  (Required)

               Indicates the name of the file to be routed to the printer.

               route_options

               SS4

               For more information, see BASIS Reference, “Op. Sys. System Specifics” where Op. Sys.
               is the name of your operating system.

Prompts:
                     FILE=
                     Change defaults (N/Y)?>

Key Points:
                    Parameters given on the ROUTE command supersede those specified in the
                     SET/ROUTE command.
                    A file must be closed to be routed.
                    Most parameters normally available for printing a file on the system are supported by
                     the BASIS routing commands.

Examples:

               SS4

               For examples, see BASIS Reference, “Op. Sys. System Specifics” where Op. Sys. is the
               name of your operating system.




416  Command References
              SALVAGE/LIBrary
              UNIX, VMS

Purpose:

              To salvage a library file damaged by a system or process failure.

              IMPORTANT: The SALVAGE/LIBRARY command is not applicable to Windows.

Syntax:

              SALVAGE/LIBrary OLD=old_lib_fd, NEW=new_lib_fd

Parameters:

              OLD=old_lib_fd                                                                   (Required)

              Specifies the name of the damaged library.

              NEW=new_lib_fd                                                                   (Required)

              Specifies the name of the new library.

Prompts:
                  OLD=
                  NEW=

Key Points:
                 The new library is not automatically placed in the library set that contained the
                  damaged library.
                 If the damaged library is in a library set, you should remove it.

Example:

              Salvage a library file.
                  FQM> SALVAGE/LIB OLD=INTRO_LIBRARY, NEW=INTRO2_LIBRARY
                  FQM> SHOW/PL=INTRO_LIBRARY/DIR, HEADER=NO
                  HELP_SCREEN                     MAIN_MENU
                  MAIN_MENU2




                                                                             Command References  417
               SAVE/View                                                         (FQM only)
Purpose:

               To place a view record into the queue area.

Syntax:

               SAVE {/View} viewbuf_ref | viewbuf_id
                      {,ERR=errlabel}
                      {,ROLLBACK=rlabel}
                      {,UID=id}
                      {,WAIt=YES | NO}

Parameters:

               viewbuf_ref | viewbuf_id                                                        (Required)

               Specifies the view record to save and the buffer where the view record is located.


               viewbuf_ref        This form should be used when saving a view record that already
                                  exists in the database.

               viewbuf_id         This form should be used when saving a view record that does not
                                  currently exist in the database.

               ERR=errlabel                                                                     (Optional)

               Specifies the label in the proc to branch to if the SAVE/View command fails.

               Note: If any of the specified term IDs are not in the result set, the system considers this
               to be a syntax error because it is caught during the parsing stage. Therefore, the system
               will not branch to the label indicated by the ERR parameter, which handles execution
               errors only. In the event of syntax errors, you can have the system transfer control to a
               label indicated by the ON/SYNTAX command.




418  Command References
              ROLLBACK=rlabel                                                                    (Optional)

              Specifies the label in the proc to branch to if the SAVE/VIEW command is rolled back in
              a deadlock situation.

              UID=id                                                                             (Optional)

              Specifies the user id to be associated with the saved view record in the queue area. The
              default is the id of the current user. The user id can contain as many as 32 letters and
              digits, but the first character must be a letter. To specify a user id other than your own or
              $NOUID, you must have the UNHOLD privilege.

              WAIT=YES | NO                                                                      (Optional)

              Indicates whether the system waits for locked resources. The default is YES.


                  YES       The system waits for locked resources to become available.

                  NO        The system does not wait for locked resources to become available. When a
                            lock occurs, the command fails and DMSTAT is set to 867.


Prompts:
                    viewbuf_id or viewbuf_ref:
                    Change defaults (N/Y) ?>

Key Points:
                   The SAVE/View command must be executed within a transaction.
                   The view record is placed in the queue area with a state of SAVED.
                   This command transfers contents of the user buffer to the queue area. An error
                    occurs if:


                       a.    Any data type conversion errors occur.

                       b.    The primary key (or the components for the primary key) are missing.

                   Required fields (except for the primary key or primary key components) may be
                    missing.
                   The view record is not validated.




                                                                              Command References  419
                   The user must have the correct privileges to SAVE records:


                     a.    The user must have HOLD privilege to SAVE records.

                     b.    The user must have UNHOLD privilege to SAVE records that are checked
                           out or saved by another user (unless the user is the dummy user $NOUID).

                   If the records were in the queue, action information (add, replace, or delete) is lost.

Examples:
               1.   In this example, the view record (ENO=1001) is placed in the queue area with a
                    status of SAVE.
                    FQM>   START/TRANS PW=EMPLOYEE
                    FQM>   GET/VIEW [ENO=1001] EMPLOYEE@A, INTENT=UPDATE
                    FQM>   SAVE/VIEW [ENO=1001] EMPLOYEE@A,
                    FQM>   FINISH/TRANS
                    FQM>
               2.   The following is an example showing how to specify the view record using the
                    [set,member] format.
                    FQM>   START/TRANS PW=EMPLOYEE
                    FQM>   GET/VIEW [1,1] EMPLOYEE
                    FQM>   SAVE/VIEW [1,1] EMPLOYEE
                    FQM>   FINISH/TRANSACTION
                    FQM>




420  Command References
              SET
Purpose:

              To set defaults for various parameters. Use of the SET command overrides any system
              defaults. For specific descriptions, see the SET commands described in the following
              pages.

Syntax:

              SET {/setoption}

Parameters:

              setoption                                                                        (Optional)

              Indicates one of the following options, each of which is described in detail within specific
              command reference descriptions below:


              /Defaults                   Sets the default parameters.

              /GV                         Sets the indicated global variable.

              /HOST_variable              Sets the indicated host variable.

              /LIBrary                    Defines the public and/or private libraries and the search
                                          order for the set.

              /Mode                       Sets the Mode parameters.

              /PICture                    Sets a default output picture for a field.

              /PV                         Sets the indicated proc variable.

              /ROUte                      Sets the file routing options.

              /THESaurus_options          Sets the THESaurus options.




                                                                                Command References  421
               /TYPE_Command             Sets a saved TYpe command definition.

               /Type_options             Sets the TYpe command options.

               /UC                       Sets the indicated user command.


Prompts:

               None.

Example:

               Note: The actual output of the commands in the examples below may vary depending
               on the operating system and/or the version of BASIS that you are using.

               The SET command lists the available options.
                     FQM> SET
                     There are several forms of the FQM SET command:
                     SET                - Lists the available SET commands
                                          (see below).
                     SET/Defaults       - Sets the default parameters.
                     SET/GV             - Sets the indicated global variable.
                     SET/HOST_variable - Sets the indicated host variable.
                     SET/LIBrary        - Defines the public and/or private
                                          libraries and the search order for
                                          the set.
                     SET/Mode           - Sets the Mode parameters.
                     SET/PICture        - Sets a default output picture for a
                                          field.
                     SET/PV             - Sets the indicated proc variable.
                     SET/ROUTE          - Sets the file routing options.
                     SET/THESaurus_opt - Sets the THESaurus options.
                     SET/TYPE_Command   - Sets a saved TYpe command definition.
                     SET/Type_options   - Sets the TYpe commands options.
                     SET/UC             - Sets the indicated user command.




422  Command References
           SET/DEFaults
Purpose:

           To assign the values used for command parameters when the parameter values are not
           supplied with the commands. Use SHow/DEFaults to see the current values.

Syntax:

           SET/Defaults
                  {,ADJacent=NO | YES}
                  {,COMma=commachar}
                  {,CONVerter=converter}
                  {,CURrency=curchar}
                  {,DB=database}
                  {,DROp=YES | NO}
                  {,INTent=USER | READ | UPDATE | EXCLUSIVE}
                  {,INTERmediate=NONE | COUNts | SETS}
                  {,LIMit=1:20}
                  {,MODel=model}
                  {,NEW_FORM_method=LEAVE_all | CLEAR_all | DEFAULT_Leave |
                    DEFAULT_Clear}
                  {,OUTput_look=YES | NO}
                  {,POInt=pointchar}
                  {,REFerences=YES | NO}
                  {,RESULT_message=YES | NO}
                  {,SAVe_look=NO | YES}
                  {,SEARCH_option=OPTIMIZE | INDEX | INDEX_ONLY | SCAN}
                  {,TIMEOUT=0:2000000}
                  {,WAIt=YES | NO}




                                                                     Command References  423
Parameters:

               ADJacent=NO | YES                                                              (Optional)

               Indicates whether a LOOK command returns exact matches on the index terms or displays
               adjacent terms if no matching term is found. The default is NO.


               NO        No terms are displayed if none matches the criterion.

               YES       Adjacent terms are displayed from among the index terms if there is no match
                         for the search term.

               COMma=commachar                                                                (Optional)

               Indicates the character used as a comma when numeric values are coded as strings. The
               default is a comma (,).

               CONVerter=converter                                                            (Optional)

               Indicates the name of the converter to use for the DML that manipulates text images when
               records are added to the database. This parameter supports only converters of the
               following types: simple, enhanced, bgml, and wp. It does not support DOC_Interchange
               converters. For more information about converter types, see Markup and Style Guide.
               SYS_SIMPLE_HARD is the default.

               CURrency=curchar                                                               (Optional)

               Indicates the character used as a currency symbol when numeric values are coded as
               strings. The default is a dollar sign ($).

               DB=database                                                                    (Optional)

               Indicates the name of the default database. The default User Data Model can be set here
               as well. Acceptable formats for indicating the name of the database and User Data Model
               are database.model and <database.model>.

               DROp=YES | NO                                                                  (Optional)

               Indicates whether the cursor is dropped from its previous assignment and reestablished
               according to the criterion of the current LOOK command. The default value is YES.


               YES       The cursor is dropped and then reestablished.



424  Command References
NO        The cursor is maintained according to its previous assignment.

INTent=USER | READ | UPDATE | EXCLUSIVE                                           (Optional)

Indicates how the database will be opened for use. The default is USER.


USER                 The intent is based on the user‟s privileges and the database
                     privileges. If possible, the database is opened with UPDATE intent.
                     Otherwise, the database is opened with READ intent.

READ                 The database can only be searched. No changes are possible.

UPDATE               Changes can be made to the database.

EXCLUSIVE            Changes can be made to the database and no other user can have the
                     database open.

INTERmediate=NONE | COUNts | SETS                                                 (Optional)

Indicates whether intermediate result sets are to be formed and, if so, what the criterion
will be for their formation. The default is NONE.


NONE           Intermediate result sets are not produced.

COUNts         Counts of members and references are returned for each intermediate
               result set, but the intermediate result sets are not saved.

SETS           Intermediate result sets are saved, and the counts of members and
               references are returned for each intermediate set.

LIMit=1:20                                                                        (Optional)

Indicates the maximum number of terms displayed by the LOOK command. The default
is 20. The limit must be a value from 1 to 20.

MODel=model                                                                       (Optional)

Indicates the name of the default User Data Model. This parameter is used when a new
default user data model is set for the default database.




                                                               Command References  425
               NEW_FORM_method=LEAVE_all | CLEAR_all | DEFAULT_Leave |
               DEFAULT_Clear                                                                        (Optional)

               Indicates the method used in USE/Screen whenever a new form is displayed. The
               NEW_FORM_method is used by the USE/Screen command after the ADD action is
               selected.


               LEAVE_all                Indicates that the current values are left in the boxes. This is the
                                        default.

               CLEAR_all                Indicates that the current values in the boxes are cleared.

               DEFAULT_Leave            Indicates that the current value of a box with a default is
                                        replaced with its default; otherwise its value is left in the box.

               DEFAULT_Clear            Indicates that the current value of a box with a default is
                                        replaced with its default; otherwise its value is cleared from the
                                        box.

               OUTput_look=YES | NO                                                                 (Optional)

               Indicates whether the terms that are output from the LOOK command will be displayed to
               the screen. The default is YES.

               POInt=pointchar                                                                      (Optional)

               Indicates the character used as a point when numeric values are coded as strings. If not
               changed, the character used is the period (.).

               REFerences=YES | NO                                                                  (Optional)

               Indicates whether result set references are computed in FIND and COMBINE commands.
               The default is YES.


               YES       References are created with the set.
                         Creating references takes longer and costs more than not creating references
                         and should be used only when highlighting is needed.
                         Unless one of the following conditions exists, the system also highlights the
                         references when you display records with the TYPE command:

                       There is a search filter on the field



426  Command References
        The field has DM-style hide markup in it

        The TYPE command references a portion of the field (TYPE STREET[1:20],
         instead of TYPE STREET, for example)

        The field value is displayed in response to the Replace action on a screen
         displayed by FQM USE/SCREEN


NO        References are not created for the result set.

RESULT_message=YES | NO                                                           (Optional)

Indicates whether the FIND and COMBINE commands display the number of members in
the result set. The default is YES.


YES       The FIND and COMBINE commands display the number of members. (If
          RESULT_message=YES but REFerences=NO, the message “Result set n
          contains m members” is displayed.)

NO        The FIND and COMBINE commands do not display the number of members.

SAVe_look=NO | YES                                                                (Optional)

Indicates whether the terms displayed by the LOOK command are saved as global
variables named DM_TERM_1, ... DM_TERM_20 and the reference counts are saved as
global variables named DM_INFO_1, ... DM_INFO_20. The default is NO.

SEARCH_option=OPTIMIZE | INDEX | INDEX_ONLY | SCAN                                (Optional)

Indicates how the system is to use the indexes to evaluate the retrieval test(s) in FIND
commands. The default is OPTIMIZE.


 OPTIMIZE              Uses the standard BASIS optimization strategy.

 INDEX                 Uses an index when searching indexed fields and scans records
                       when searching on non-indexed fields. If a user specifies an
                       indexed field and an incompatible test operator in the FIND
                       command, the system displays an error message.




                                                               Command References  427
                   INDEX_ONLY        Searches only indexed fields and uses their indexes. If a non-
                                     indexed field or test operator incompatible with indexed fields is
                                     specified in the search command, the system returns an error
                                     message.

                   SCAN              Scans records when searching indexed or non-indexed fields.
                                     Ignores all indexes.

               TIMEOUT=0 | 2000000                                                             (Optional)

               Specifies the maximum number of CPU seconds allowed to process a FIND command.
               When the CPU time limit is reached, the system returns an error message.

               Your system administrator can also set a time limit by using the DM_FIND_TIMEOUT
               environment variable. You cannot specify a value for TIMEOUT that is greater than the
               value specified for DM_FIND_TIMEOUT. The default is 0, which means no time limit.

               For more information about DM_FIND_TIMEOUT and other environment variables, see
               BASIS Reference, “Environment Variables.”

               WAIt=YES | NO                                                                   (Optional)

               Indicates whether the system waits for items locked by other users to become available.
               The default is YES.

Prompts:
                    All parameters are optional, do you wish to change any (Y/N)? >

Key Points:
                   If you do not use the SET/DEFaults command, BASIS uses the following defaults:


                     ADJacent                     = NO

                     COMMA                        =,

                     CONVerter                    = SYS_SIMPLE_HARD

                     CURRENCY                     =$

                     DB                           = TOUR

                     DROp                         = YES




428  Command References
    INTENT                        = USER

    INTERmediate                  = NONE

    LIMIT                         = 20

    MODEL                         = ALL

    NEW_FORM_method               = LEAVE_ALL

    OUTput_look                   = YES

    POINT                         =.

    REFerences                    = YES

    RESULT_message                = YES

    SAVe_look                     = NO

    SEARCH_option                 = OPTIMIZE

    TIMEOUT                       = 20

    WAIT                          = YES

    The SET/DEFaults command is often used in login procedures to set the appropriate
    default values for a user or a specific database. If a SET/DEFaults command is used
    within a login procedure, it is likely that the default parameter values listed above
    will not apply. You can use the SHow/DEFaults command to view the default values
    of parameters for a specific work session.
   Setting REFerences to No will improve retrieval speed, however, references will not
    be highlighted in the TYPE command.




                                                            Command References  429
Examples:

               Note: The actual output of the commands in the examples below may vary depending
               on the operating system and/or the version of BASIS that you are using.
               1.   You can set default parameters in response to a prompt (a.) or enter the parameters
                    and values with the command (b.). When you press [ENTER] in response to a
                    prompt, the default value is used.
               a.   FQM> SET/DEFAULTS
                    All parameters are optional.             Do you wish to change any
                    (Y/N)? Y
                    DB=
                    MODEL=
                    POINT=
                    COMMA=
                    CURRENCY= #
                    LIMIT= 5
                    INTENT= READ
                    SAVe_look=
                    WAIT=
                    RESULT_message=
                    DROp=
                    INTERmediate=
                    ADJacent=
                    REFerences=
                    NEW_FORM_method=
                    CONVerter=
                    TIMEOUT=
                    SEARCH_option=
                    OUTput_look=
               b.   FQM> SET/DEFAULTS,CURRENCY=#,LIMIT=5,INTENT=READ

               2.   An error message is displayed if a parameter is spelled incorrectly.
                    FQM> SET/D,CURRANTCY=#

                          V
                    SET/D,CURRANTCY=#
                    USER ERROR( 7067). Invalid parameter for the
                    SET/Defaults command.




430  Command References
3.   The default intent for opening a database is USER. The SHOW/DB command
     reveals that the TACME.FQMA database was opened with UPDATE intent, i.e., by a
     user with Add, Modify or Delete privilege for TACME.FQMA.
     FQM> OPEN/DB TACME.FQMA
     FQM> SHOW/DB
     The open database models are:

     Intent     Version     Database.Model         Kernel     Primary Name
     ------     -------     --------------         ------     ------------
     Update        0        <TACME.FQMA>           DMKA1      TACME   (default)
4.   The SET command changes the default INTENT to READ. The next OPEN/DB
     command opens the TOUR.ALL database with READ intent, whether the user has
     update privileges for TOUR.ALL or not, because READ intent is now the default.
     (You could have overridden this default for TOUR.ALL by adding the parameter
     INTENT=UPDATE to your OPEN/DB command.)
     FQM> SET/DEFAULT INTENT=READ
     FQM> OPEN/DB TOUR.ALL
     FQM> SHOW/DB
     The open database models are:

     Intent     Version     Database.Model         Kernel     Primary Name
     ------     -------     --------------         ------     ------------
     Update        0        <TACME.FQMA>           DMKA1      TACME
     Read          0        <TOUR.ALL>             DMKA1      TOUR    (default)
5.   In the previous display, TOUR.ALL is the default database. You can change the
     default database using the SET command.
     FQM> SET/DEFAULT DB=TACME.FQMA
     FQM> SHOW/DB
     The open database models are:

     Intent     Version     Database.Model         Kernel     Primary Name
     ------     -------     --------------         ------     ------------
     Update        0        <TACME.FQMA>           DMKA1      TACME   (default)
     Read          0        <TOUR.ALL>             DMKA1      TOUR




                                                            Command References  431
               SET/GV
Purpose:

               To assign a value to a global variable or a substring of a global variable.

Syntax:

               SET/GV globalvar {[exp{:exp}]}=value

Parameters:

               globalvar                                                                          (Required)

               A 1- to 32-character name that identifies a global variable. If the variable already exists,
               the SET/GV command replaces the value of the variable (or the indicated substring of the
               variable).

               [exp{:exp}]                                                                         (Optional)

               Indicates the starting and ending character positions of a substring of the global variable.
               This parameter is optional. You need to use it only if you want to assign or replace the
               value of a portion (a substring) of the variable.

               value                                                                              (Required)

               Specifies an integer, literal or expression assigned to the global variable (or to the
               indicated substring of the variable).

Prompts:
                   globalvar{[exp{:exp}]}=value:

Key Points:
                  The BASIS system establishes several global variables. Because the names of these
                   system global variables begin with the letters “DM”, you should avoid using names
                   that begin with “DM” for variables. Here are four of the global variables that the
                   system maintains:


                       DMSTAT             Status code returned by last command.

                       DM_DB              Name of the default database.




432  Command References
                  DM_MODEL             Name of the default model.

                  DM_UID               Interactive user id.

                In substring references used with the SET/GV command, the starting and ending
                 character positions must be greater than zero, and the ending position must be greater
                 than or equal to the starting position. If you specify a substring that is shorter than
                 the value you supplied, the system pads the value with blanks on the right. You can
                 use an asterisk (*) as the ending position to indicate the last character in the variable.

Examples:
            1.   You can set global variables to functions such as $TIME and $DATE, which return
                 the current system time and date.
                 FQM> SET/GV NOW=$TIME
                 FQM> SHOW/GV NOW
                    NOW = 11:54:04
                 FQM> SET/GV TODAY=$DATE
                 FQM> SHOW/GV TODAY
                    TODAY = Apr 17, 1984
                 FQM>
            2.   When you use the SET/GV command to store a character string (XX CODE) in a
                 global variable (ANERR), you must enclose the character string in quotes.
                 FQM> SET/GV ANERR=XX_CODE
                 FQM> SHOW/GV ANERR
                    ANERR =
            3.   The first SET/GV command in this example shows the proper use of quotes with a
                 character string value („XX CODE‟). The second SET/GV command does not need
                 quotes because it stores the value 10 as an integer. The substring reference [1:2] tells
                 the system to replace the first two characters of the variable with the number 10.
                 FQM> SET/GV ANERR='xx_code'
                 FQM> SHOW/GV ANERR
                    ANERR = xx_code
                 FQM> SET/GV ANERR[1:2]=10
                 FQM> SHOW/GV ANERR
                    ANERR = 10_code
                 FQM>




                                                                             Command References  433
               4.   This example shows that you can use global variables in expressions. It also shows
                    that you can use expressions in the SET/GV command. The first two SET/GV
                    commands copy the current system time into the variables START and END. The
                    last SET/GV command stores the difference between the START and END variables
                    in the variable ELAPSE.
                    FQM> SET/GV START=$HHMMSS
                    FQM> SHOW/GV START
                       START = 121738
                    FQM> SET/GV END=$HHMMSS
                    FQM> SHOW/GV END
                       END = 122136
                    FQM> SET/GV ELAPSE = END-START
                    FQM> SHOW/GV ELAPSE
                       ELAPSE = 398
                    FQM>
               5.   This example shows how nested procs can share a global variable. The main proc
                    executes two nested procs. DEPAVG calculates the average number of dependents
                    per employee. DEPGTAVG uses this average to calculate which employees have
                    more than the average number of dependents.

                    Main Proc:
                    @DEPAVG
                    @DEPGTAVG

                    The DEPAVG Proc:
                    FIND EMPLOYEE END,RESULT=NO
                    ACQUIRE/PV MEMBERS N1=EMPTOT
                    *
                    FIND DEPENDENT END,RESULT=NO
                    ACQUIRE/PV MEMBERS N1=DEPTOT
                    *
                                             1
                    SET/GV AVG=DEPTOT/EMPTOT
                    *
                    TELL 'The average number of dependents per employee is ',AVG




434  Command References
    The DEPGTAVG Proc Segment:
    TELL 'These employees have more than the average +
          number of dependents'
    *
    OBTAIN/VIEW DEPENDENT.ENO@A, +
       POSITION=LAST,ERR=DEPERR1,INTENT=READ,KEY=DEPENO
    LOOP
       ASSIGN/PV DEPNO = DEP_NO@A
                         2
       IF,(DEPNO GT AVG)
       GET/VIEW [ENO=!DEPENO!]EMPLOYEE@B
       TYPE NAME,BUFFER=B,DEP_NO,BUFFER=A,LABEL=NO
       END_IF
       OBTAIN/VIEW +
          DEPENDENT.ENO@A,POSITION=PRIOR_DIFFERENT,+
          KEY=DEPENO,INTENT=READ,ERR=DEPERR2,END=$RETURN
    END_LOOP
    :
    :

    1
      In the DEPAVG proc, the SET/GV command creates the global variable AVG,
which stores the average number of dependents per employee.
    2
       In the DEPGTAVG proc, the IF command uses the global variable AVG to
determine which employees have a greater than average number of dependents. If AVG
was a proc variable instead of a global variable, it could be accessed only by the proc that
created (DEPAVG) it and not by the proc DPGTAVG.




                                                               Command References  435
               SET/HOST_variable
Purpose:

               To assign a value to a host system variable.

Syntax:

               SET/HOST_variable hostvar=value

Parameters:

               hostvar                                                                          (Required)

               Specifies the name of the host variable to be set.

               value                                                                            (Required)

               Specifies the value to be assigned to the host variable. This value can be any legal proc
               expression.

Prompt:
                   hostvar=value:

Key Points:
                  The SET/HOST_variable command assigns a value to a host variable during the
                   execution of a BASIS interactive module. The host variables established with this
                   command are local in scope.
                  You can use the SET/HOST_variable command to assign values to environment
                   variables. An environment variable is a host system variable that defines an option
                   in the BASIS environment. Here are some examples of environment variables:


                       DM_AIDS            Indicates whether interactive modules issue a prompt asking
                                          users if they want to review the user aids.

                       DM_EDIT            Determines which host system editor is invoked in interactive
                                          modules that support the RECALL/EDIT command.

                       DM_MODE            Indicates whether the user‟s process requires interactive or
                                          batch processing.




436  Command References
                     DM_SPAWN        Indicates whether the SPAWN command is disabled or active.

            For more information about environment variables, see BASIS Reference, “Environment
            Variables.”

Examples:
            1.   Assume that FQM is executed by a host system command procedure, and that the
                 proc shown is immediately executed. The proc prompts the user for an employee
                 name and adds employee view records to the database.

                 Proc Segment:
                 SET/PV ERR='F'
                 SET/HOST_VARIABLE REJ_FILE='     '
                 *
                 TOP:
                    MAKE/VIEW EMPLOYEE@A
                    INQUIRE/PV NAME,'Enter employee''s name>'
                    *
                    WHILE $LC(NAME) GT 0
                       ASSIGN/FIELD NAME=!$STRING(NAME)!
                          :
                          :
                       START/TRANSACTION PW=EMPLOYEE
                                                         1
                       ADD/VIEW EMPLOYEE@A, ERR=ADD_ERR
                       FINISH/TRANSACTION
                       MAKE/VIEW EMPLOYEE@A
                       INQUIRE/PV NAME,'Enter employee''s name>'
                    END_WHILE
                    *
                                          2
                    IF (ERR EQ 'T') THEN
                                                                               3
                       SET/HOST_VARIABLE REJ_FILE='EMPLOYEE_REJ'
                    END_IF
                    RETURN

                 *
                          4
                 ADD_ERR:
                    ABORT/TRANSACTION
                    SET/PV ERR='T'
                    TYPE *,BUF=A,FILE='EMPLOYEE_REJ',APPEND=YES
                    JUMP TOP

                 1
                  If an error occurs during the execution of the ADD/View command, control
            branches to the ADD_ERR label.
                 2
                    When the user is done adding view records (the user enters [RETURN] to signal
            this), the IF command checks whether any errors occurred. The SET/PV command that
            follows the ADD_ERR label sets the variable ERR equal to „T‟ to indicate an error has
            occurred and the reject file contains at least one employee name.



                                                                       Command References  437
                    3
                     If any errors occurred, the SET/HOST_variable command sets the host variable
               REJ_FILE to the name of the reject file. You can access this host variable at the
               Operating System level. The system level procedure that originally executed FQM or
               BCL can also access the host variable REJ_FILE.
                    4
                      The commands following the ADD_ERR label write the current employee name to
               a reject file called EMPLOYEE_REJ.
               2.   The SET/HOST_variable command accepts any valid expression for the value of the
                    host variable. In this example, the ASSIGN/HOST_VARIABLE command copies
                    the value of the environment variable DM_DB_DATABASE into the proc variable
                    DATABASE. For more information, see BASIS Reference, “Environment
                    Variables.”

                    Proc Segment:
                    INQUIRE DBNM, 'Enter the number of the database.'
                    WHILE (DBNM NE 9)
                       SET/HOST DM_DB_DATABASE='ACME'//DBNM
                       ASSIGN/HOST DATABASE=DM_DB_DATABASE
                       OPEN/DB DATABASE.FQMA
                       TELL 'The FQMA model of the !DATABASE! is open.'
                    * execute the proc that processes the database
                       @PROCESS
                       CLOSE/DB DATABASE.FQMA
                       INQUIRE/PV DBNM, 'Enter the number of the database.'
                    END_WHILE
                    RETURN




438  Command References
              SET/LIBrary
              UNIX, VMS

Purpose:

              To define a public and/or private library set and the order in which the system searches
              the library set for a proc. A library set is a collection of library files to be searched when
              LIB=$PRIvate, $PUBlic, or * in the @, DELete/PLibrary, EXPort/PLibrary,
              IMPort/PLibrary, SHOW/PLibrary/Proc, and SHOW/PLibrary/Dir command.

              IMPORTANT: The SET/LIBRARY command is not applicable to Windows.

Syntax:

              SET/LIBrary {PUBLIC {=lib_search | =(lib_search {, lib_search} 0:9)} |
                     {PRIVATE {=lib_search | =(lib_search {, lib_search} 0:9)}

Parameter:

              lib_search                                                                          (Optional)

              Specifies the name of a library file. This may be a list of libraries or the keyword
              $FILE_base which means the lib_search parameter is treated like a file name.
              $FILE_base tells the system that you want to search through the files in the specified
              directory for the proc.

Prompt:
                  {PUBLIC {=lib_search}} {PRIvate {=lib_search }}:

Key Points:
                 Private libraries cannot be referenced by other users.
                 Public libraries can be read, but cannot be updated. Unlike private libraries, public
                  libraries can be shared.
                 If the PUBLIC or PRIVATE keyword is specified without any libraries, the search
                  order for that library set is deleted.
                 The order in which the libraries are specified becomes the search order for the library
                  set.




                                                                               Command References  439
                    $FILE_base allows you, in effect, to define your current directory as a proc lib file
                     and the system will use it as part of its search list. The system will look at files with
                     an extension of .PRC and, if it finds one matching the proc name given, will execute
                     it. The $FILE_base option can be specified anywhere in the search list or can be
                     used standalone.
                    The search order of a library set is deleted at the end of the current session. To avoid
                     issuing the same SET/LIBrary command at the beginning of each session, place the
                     command in your user login file.

Examples:
               1.    Establish the search order for the private library set.
                     FQM> SHOW/LIB PRI
                     No private library set files defined.
                     FQM> SET/LIB PRI=(INTRO_LIBRARY,MENU_LIBRARY)
                     FQM> SHOW/LIB PRI
                     Private library set files:
                     -------------------------

               SS1
                     Host file descriptor for INTRO_LIBRARY
                     Host file descriptor for MENU_LIBRARY
               2.    Delete the search order for the private library set.
                     FQM> SHOW/LIB PRI
                     Private library set files:
                     -------------------------

               SS1
                     Host file descriptor for INTRO_LIBRARY
                     Host file descriptor for MENU_LIBRARY
                     FQM> SET/LIB PRI
                     FQM> SHOW/LIB PRI
                     No private library set files defined.
               3.    Establish the search order for the private library set by using the $FILE_base. Now
                     the proc files in the current directory are searched.
                     FQM> SHOW/LIB PRI
                     No private library set files defined.
                     FQM> SET/LIB PRI=$FILE
                     FQM> SHOW/LIB PRI
                     Private library set files:
                     --------------------------
                     $FILE_base
                     FQM>




440  Command References
4.    Establish the search order for the public library set.
      FQM> SHOW/LIB PUB
      No public library set files defined.
      FQM> SET/LIB PUB=(PROCS_LIBRARY,+
      ....MATH_ROUTINE_LIB,INDEX_LIBRARY)
      FQM> SHOW/LIB PUB
      Public library set files:
      ------------------------

SS1
      Host file descriptor for PROCS_LIBRARY
      Host file descriptor for MATH_ROUTE_LIB
      Host file descriptor for INDEX_LIBRARY
5.    Delete the search order for the public library set.
      FQM> SHOW/LIB PUB
      Public library set files:
      ------------------------

SS1
      Host file descriptor for PROCS_LIBRARY
      Host file descriptor for MATH_ROUTE_LIB
      Host file descriptor for INDEX_LIBRARY
      FQM> SET/LIB PUB
      FQM> SHOW/LIB PUB
      No public library set files defined.




                                                               Command References  441
               SET/Mode
Purpose:

               To define the options that the BASIS system uses for the following settings:


                          ABORT_on_error                PAUsehelp

                          BREAK                         TALK
                                                                   1
                          CORRECT                       TERMinal

                          ECHOProc                      TRACE

                          ERROR                         TRACEFile

                          INTERactive_prompts

               To see the current mode settings, use the SHow/Mode command.

Syntax:

               SET/Mode
                     {,ABORT_on_error=NO |YES}
                     {,BREAK=Kill | Pause}
                     {,CORRECT=NO | YES}
                     {,ECHOProc=NO | YES}
                     {,ERROR=$ABORT | $CONTINUE}
                     {,INTERactive_prompts=YES | NO}
                     {,PAUsehelp=YES | NO}
                     {,TALK=Standard | Expert | Novice}
                                          1
                     {,TERMinal=terminal}
                     {,TRACE=NO | YES}
                     {,TRACEFile=filedescriptor}
                   1
                       The TERMINAL parameter is not applicable to Windows.




442  Command References
Parameters:

              ABORT_on_error=NO | YES                                                       (Optional)

              Indicates the action taken when the system encounters an unhandled error. Usually used
              in a batch mode to stop the session when an unhandled error occurs. The default is NO.


              NO       When an unhandled error occurs the error is displayed and you will be
                       prompted for the next interactive command. If you are in a proc, you will be
                       exited from the proc.

              YES      The system exits the module when an error is found.

              BREAK=Kill | Pause                                                            (Optional)

              Indicates the action taken when the user presses the [BREAK] key. The default is Kill.


              Kill        The [BREAK] key stops command execution prior to its normal
                          completion. The system returns a prompt.

              Pause       The [BREAK] key causes a temporary interruption of the command
                          execution. The system reports the processing status of the command and
                          then continues command execution at the user‟s option.

              CORRECT=NO | YES                                                              (Optional)

              Indicates the action taken when an error is found in a command. The default is NO.


              NO       If the system does not recognize your command, it displays a message followed
                       by the prompt. You can use the RECall or execute command (/) to revise and
                       execute the command.

              YES      If the system does not recognize your command, it displays a message followed
                       by the “Correct the current statement (Y/N)?>” prompt. The command can be
                       revised and re-executed.




                                                                          Command References  443
               ECHOProc=NO | YES                                                                  (Optional)

               Indicates whether the system displays each proc command it executes. The default is NO.


               NO       The system does not display the commands in a proc as it executes them.

               YES      The system displays the commands in a proc as it executes them.

               ERROR=$ABORT | $CONTINUE                                                           (Optional)

               Indicates the proc error mode. The default is $ABORT.


               $ABORT              The proc aborts upon finding an error that is not handled by an
                                   ERR=branch or an ON/SYNTAX or ON/EXCEPTION command.

               $CONTINUE           The proc continues to execute after the system identifies an
                                   unhandled error.

               INTERactive_prompts=YES | NO                                                       (Optional)

               Indicates where the system receives input. The default is YES.


               YES       Input is received from user‟s interactive responses to prompts.

               NO        The system reads the proc for input.

               PAUsehelp=YES | NO                                                                 (Optional)

               Indicates whether the help feature pauses before displaying the next screen of
               information. The default is YES.


               YES       When the help information has filled a screen, the system issues a prompt
                         asking the user whether to continue to the next screen.

               NO        The system displays the entire explanation of a topic, scrolling to the next
                         screen without pausing.




444  Command References
TALK=Standard | Expert | Novice                                                  (Optional)

Indicates the level of detail in the system messages. The default is Standard.


Standard       The system issues moderately detailed messages.

Expert         The system issues brief messages.

Novice         The system issues very detailed messages.

TERMinal=terminal                                                                (Optional)

Indicates the type of terminal used for the session. Your terminal type default is set by
your SA or DBA. To use your site‟s default terminal type, enter * for terminal.



 For                      Valid terminal selection is

 NT                       not applicable

 UNIX                     CURSES,VT100

 VMS                      VT100, VT52, EDT100, EDT52


TRACE=NO | YES                                                                   (Optional)

Indicates whether the system writes the commands entered by a user to the trace file (see
below). SET/MODE TRACE=YES cannot be used as a command inside a proc. The
default is NO.


NO         The system does not write commands to a trace file.

YES        The system writes commands to a trace file.




                                                               Command References  445
               TRACEFile=filedescriptor                                                          (Optional)

               Indicates the name of the file that records the commands when TRACE=YES.



                   Operating system        Default trace file name

                   NT                      The default trace file name is trace.prc

                   UNIX                    The default trace file name is trace.prc

                   VMS                     The default trace file name is TRACE.PRC


               For more information, see BASIS Reference, “Op. Sys. System Specifics” where Op. Sys.
               is the name of your operating system.

Prompt:
                     All parameters are optional, do you wish to change any (Y/N)? >

Key Points:
                    If you do not execute a SET/MODE command, the system will assign the following
                     default values:

                     BREAK=Kill
                     CORRECT=NO
                     TALK=Standard
                                                                      1
                     TERMINAL=* (uses the user default terminal type)
                     ABORT_on_error=NO
                     ECHOProc=NO
                     TRACE=NO
                     TRACEFile= (defaults vary depending on operating system)
                     ERROR=$ABORT
                     PAUsehelp=YES
                     INTERactive_prompts=YES
                     1
                         The TERMINAL parameter is not applicable to Windows.

                     Because the default value for the TRACE file is system specific, it may differ slightly
                     from the value shown above.
                    You can use the SET/MODE command in login procs to set the appropriate default
                     modes for a group of users or a database.




446  Command References
Examples:
            1.   You can set mode parameters in response to prompts (a.) or by entering the values
                 for parameters with the SET/Mode command (b.). When you press [ENTER] in
                 response to a prompt, the default value is used.
            a.   FQM> SET/MODE
                 All parameters are optional, do you wish to change any +
                    (Y/N)? > Y
                 BREAK=
                 CORRECT=
                 TALK= NOVICE
                 TERMinal= VT100
                 ABORT_on_error= YES
                 ECHOProc= YES
                 TRACEFile=
                 TRACE=
                 ERROR=
                 PAUsehelp= NO
                 INTERactive_prompts=

            b.   FQM> SET/MODE PAU=NO,TALK=NOVICE,TERM=VT100, +

                 ... ABORT=YES,ECHOP=YES
            2.   The TRACE=YES mode causes each executed command to be written to a sequential
                 file named by the TRACEFile parameter. Unless you specify a name for the trace
                 file, the executed commands are written to the default trace file for your host system.
                 If TRACE=YES, commands continue to be written to the trace file until you set the
                 mode to TRACE=NO. In example 2a, the executed commands are written to the
                 default file. In example 2b the executed commands are written to a trace file named
                 NEW.




                                                                          Command References  447
               a.    FQM> SET/MODE TRACE=YES
                     FQM> FIND EMPLOYEE WHERE DNO=101
                           Result set 1 contains 12 references to 12 members.
                     FQM> SET/MODE TRACE=NO
                     FQM> SHOW/PF TRACE,HEADER=NO
                     FIND EMPLOYEE WHERE DNO=101
                     SET/MODE TRACE=NO

                     FQM> @TRACE
                     FIND EMPLOYEE WHERE DNO=101
                            Result set 2 contains 12 references to 12 members.
                     SET/MODE TRACE=NO
                     RETURN

               SS1

               b.    FQM> SET/MODE TRACEFILE = NEW
                     FQM> SET/MODE TRACE=YES
                     FQM> FIND EMPLOYEE WHERE SALARY GT 5000
                           Result set 3 contains 1 references to 1 members.
                     FQM> SET/MODE TRACE=NO
                     FQM> SHOW/PF NEW,HEADER=NO
                     FIND EMPLOYEE WHERE SALARY GT 5000
                     SET/MODE TRACE=NO

                     FQM> @NEW
                     FIND EMPLOYEE WHERE SALARY GT 5000
                            Result set 4 contains 1 references to 1 members.
                     SET/MODE TRACE=NO
                     RETURN
               3.    If ECHOProc=NO (a.) the system does not display the proc commands as it executes
                     them. If ECHOProc=YES (b.) the system displays each proc command as it
                     executes. The ECHOProc parameter is a valuable tool for debugging procs.
               a.    FQM> SET/MODE ECHOPROC=NO
                     FQM> @TRACE
                           Result set 5 contains 12 references to 12 members.
               b.    FQM> SET/MODE ECHOPROC=YES
                     FQM> @TRACE
                     FIND EMPLOYEE WHERE DNO=101
                            Result set 6 contains 12 references to 12 members.
                     SET/MODE TRACE=NO
                     RETURN




448  Command References
4.   If CORRECT=YES, the system prompts you until you are finished making
     corrections. If CORRECT=NO, you can use the RECall or slash (/) command to re-
     execute the last command submitted. When you enter RECall or /, you can make
     corrections to the command before executing it again.
     FQM> SET/MODE CORRECT=YES
     FQM> FIND EMKPLOYEE WHERE NAME='JOHN'*

          V
     FIND EMKPLOYEE WHERE NAME='JOHN'*
     USER ERROR( 864). View Name translation failed.
     The view is not defined.
     Correct the current statement (Y/N)? > Y
     oldstring> MKP
     newstring> MP
     FIND EMPLOYEE WHERE NAME='JOHN'*
        1 changes made.
     More corrections (Y/N)? > N
     FQM> FIND EMPLOYEE WHERE NAME='JOHN'*
            Result set 7 contains 2 references to 2 members.




                                                         Command References  449
               SET/PICture
Purpose:

               To define a default output picture for a field. Up to 25 concurrent default pictures may be
               defined via the SET/PICture command.

Syntax:

               SET/PICture field_id:picture {,ERR=errlabel}

Parameters:

               field_id                                                                        (Required)

               Indicates the view and field name for which the output picture is defined. Format for
               field_id is viewname.fieldname.

               picture                                                                         (Required)

               Indicates the output picture. A picture, complete with justification characters (< and >),
               must be specified. For more information about picture specifications, see the Key Points
               below.

               ERR=errlabel                                                                     (Optional)

               Indicates the label within a command procedure to branch to if the SET/PICture
               command fails.

Prompts:
                   field_id: picture:
                   Change defaults (Y/N)? >

Key Points:
                  When a field is specified on a TYpe command, FQM looks up the default picture for
                   that field. A default picture is determined from one of three places. First, the
                   SET/PICture table is searched for a user-defined default picture. If one is not found,
                   the Definition Database is checked for a default picture that was specified during the
                   definition of the field. If a picture is not found, a reasonable default (based on the
                   data type of the field) is used. Any picture specified on the TYpe command for the
                   field is merged with the default picture. Where there are conflicts, specifications for
                   the field in the TYpe command take precedence.




450  Command References
   Specifications in a new SET/PICture command for a field are not merged with the
    previous SET/PICture specifications, but completely override the previous
    SET/PICture specifications.
   The output picture specifies the format in which the values of fields are displayed. A
    picture consists of 3 basic components:


    - Column width,
    - Justification within the column,
    - Special qualifiers.
   Column width defines the character width of the column. The column width used
    depends on the type of data value.


    -    Integer, Hexidecimal, and Octal values can be displayed using a 1- to 80-
         character wide column. For example, 5 indicates a column 5 characters wide.

    -    Character values can be displayed using a 1- to 512-character wide column. For
         example, 30 indicates a column 30 characters wide.

    -    Real values (values containing a decimal point) can be displayed using a 1- to
         80-character wide column. The number of digits to the right of the decimal
         point must be indicated. For example, 10.2 indicates a column 10 characters
         wide with up to 8 digits to the left of the decimal point and up to 2 digits to the
         right of the decimal point.

   Justification, defined using the > and < characters, indicates where the value is
    displayed within the column. The size specification is provided within the > and <
    characters. For example, <10< indicates the data is left justified within a 10
    character column.


    <<       Left justify.

    >>       Right justify.

    <>       Center value within column.

    ><       Squeeze value to occupy as little space as needed, up to the specified
             column width.




                                                                 Command References  451
                   Special qualifiers define how the value is presented. The qualifiers follow the
                    column size specification within the justification characters. For example, >10/C>
                    indicates the data is right justified within a 10 digit column. The /C qualifier
                    indicates commas are inserted to the left of each group of 3 digits. (The value
                    900000 is presented as 900,000.) Qualifiers are grouped into categories. For a list of
                    special qualifiers, see the “Picture Syntax” section of the TYpe command below in
                    this chapter.

Examples:
               1.   You can supply a picture for a field in response to the prompt (a.) or with the
                    command (b.).
               a.   FQM> SET/PICTURE
                    field_id:picture: EMPLOYEE.NAME:<15<
                    Change defaults (N/Y)? > N

               b.   FQM> SET/PICTURE EMPLOYEE.NAME:<15<

               2.   You must enter both the view name and the field name. Separate them with a period
                    (.).
                    FQM> SET/PICTURE NAME:<15<

                                V
                    SET/PICTURE NAME:<15<
                    USER ERROR( 7604). Missing required view type name for
                    this command.
                    FQM> SET/PICTURE EMPLOYEE.NAME:<15<

               3.   If a picture already exists when a new picture is defined, the new picture completely
                    replaces the old picture.
                    FQM> SHOW/PICTURE
                       <TOUR.ALL>EMPLOYEE.NAME : <15<
                    FQM> SET/PICTURE EMPLOYEE.NAME:<30/'Employee name'<
                    FQM> SHOW/PICTURE
                       <TOUR.ALL>EMPLOYEE.NAME : <30/'Employee name'<




452  Command References
4.   A picture for the NAME field includes a 15 character column labeled Employee
     Name. The SALARY picture defines a 10 character column. Each value is printed
     with 2 places to the left of the decimal, commas placed every three digits apart and a
     floating currency symbol. The COMM picture resembles that of SALARY except
     that it is 2 digits shorter. Notice what the length does to the column heading.
     FQM> SET/PICTURE EMPLOYEE.NAME:<15/'Employee name'<
     FQM> SET/PICTURE EMPLOYEE.SALARY:>10.2/DC/C>
     FQM> SET/PIC EMPLOYEE.COMM:>8.2/DC/C>
     FQM> SHOW/PICTURE
        <TOUR.ALL>EMPLOYEE.COMM : >8.2/DC/C>
        <TOUR.ALL>EMPLOYEE.NAME : <15/'Employee name'<
        <TOUR.ALL>EMPLOYEE.SALARY : >10.2/DC/C>
     FQM> TYPE NAME,SALARY,COMM

     Employee name          Sal/Month       Com/Mont
                                            h
     ---------------        ----------      --------
     DOE, ABRAHAM            $1,050.00
     WILLIAMS, JAMES         $2,500.00
     LEWIS, BILL             $1,200.00
     PETERS, BRENDA          $1,250.00
     LYONS, JEANNE           $1,300.00
     BODNARUK, ANN             $811.00
     ANGELLO, LUKE           $1,477.00
     SCHAUER, RACHEL         $1,378.00
     TODD, FAY               $1,053.00
     SARCHIN, TONY           $1,395.00        $432.00
     KELLY, CINDY            $2,713.00
     ROBINSON, JOHN          $2,899.00




                                                               Command References  453
               SET/PV
Purpose:

               To assign a value to a proc variable or a substring of a proc variable.

Syntax:

               SET/PV procvar {[exp{:exp}]}=value

Parameters:

               procvar                                                                            (Required)

               A 1- to 32-character name that identifies a proc variable. If the variable already exists,
               the SET/PV command replaces the value of the variable (or the indicated substring of the
               variable).

               [exp{:exp}]                                                                        (Optional)

               Indicates the starting and ending character positions of a substring of the proc variable.
               This parameter is optional. You need to use it only if you want to assign or replace the
               value of a portion (a substring) of the variable.

               value                                                                              (Optional)

               Specifies an integer, literal or expression assigned to the proc variable (or to the indicated
               substring of the variable).

Prompt:
                   procvar{[exp{:exp}]}=value

Key Point:
                  In substring references used with the SET/PV command, the starting and ending
                   character positions must be greater than zero, and the ending position must be greater
                   than or equal to the starting position. If you specify a substring that is shorter than
                   the value you supplied, the system pads the value with blanks on the right. You can
                   use an asterisk (*) as the ending position to indicate the last character in the variable.




454  Command References
Examples:
            1.   You can set proc variables to functions such as $TIME and $DATE, which return the
                 current system time and date.
                 FQM> SET/PV NOW=$TIME
                 FQM> SHOW/PV NOW
                    NOW = 11:54:04
                 FQM> SET/PV TODAY=$DATE
                 FQM> SHOW/PV TODAY
                    TODAY = Apr 17, 1984
                 FQM>
            2.   When you use the SET/PV command to store a character string (XX_CODE) in a
                 proc variable (ANERR), you must enclose the character string in quotes. (See
                 example 3.)
                 FQM> SET/PV ANERR=XX_CODE
                 FQM> SHOW/PV ANERR
                       ANERR=
            3.   The first SET/PV command in this example shows the proper use of quotes with a
                 character string value („XX_CODE‟). The second SET/PV command does not need
                 quotes because it stores the value 10 as an integer. The substring reference [1:2] tells
                 the system to replace the first two characters of the variable with the number 10.
                 FQM> SET/PV ANERR='XX_CODE'
                 FQM> SHOW/PV ANERR
                    ANERR = XX_CODE
                 FQM> SET/PV ANERR[1:2]=10
                 FQM> SHOW/PV ANERR
                    ANERR = 10_CODE
                 FQM>
            4.   This example shows that you can use proc variables in expressions. It also shows
                 that you can use expressions in SET/PV commands. The first two SET/PV
                 commands copy the current system time into the variables START and END. The
                 last SET/PV command stores the difference between the START and END variables
                 in the variable ELAPSE.




                                                                           Command References  455
                    FQM> SET/PV START=$HHMMSS
                    FQM> SHOW/PV START
                       START = 121738
                    FQM> SET/PV END=$HHMMSS
                    FQM> SHOW/PV END
                       END = 122136
                    FQM> SET/PV ELAPSE = END-START
                    FQM> SHOW/PV ELAPSE
                       ELAPSE = 398
                    FQM>
               5.   This proc processes each member of a result set and calculates the average number of
                    hours per assignment. The SET/PV and ASSIGN/PV commands assign these values
                    to the proc variables:


                    MEMTOT             The total number of members in the result set.

                    M                  The number of the member currently being processed.

                    HOUR               The value of the HOURS field.

                    HOURTOT            The total number of hours processed.

                    HOURAVG            The average number of hours per assignment.

                    Proc Segment:
                    FIND ASSIGNMENT END, RESULT=NO
                    ACQUIRE/PV MEMBERS N1=MEMTOT
                    SET/PV HOURTOT=0
                    FOR M=1, MEMTOT
                       GET/VIEW [0,!M!]ASSIGNMENT
                                            1
                       ASSIGN/PV HOUR=HOURS
                       SET/PV HOURTOT=HOURTOT+HOUR
                    END_FOR
                    *
                    SET/PV HOURAVG=HOURTOT/MEMTOT
                    TELL 'THE AVERAGE NUMBER OF HOURS: !HOURAVG!.'

                    1
                      Note that you must use the ASSIGN/PV command to assign a database field value
               to a variable before you manipulate that field value. You cannot use the SET/PV
               command to store a field in a variable.




456  Command References
              SET/ROUte
Purpose:

              To define the default routing parameters. If no parameters are specified, all route
              parameters are restored to the system default. Use the SHow/ROUte command to see the
              current routing defaults and the ROUTE/FILE command to route a file to a printer.

Syntax:

              SET/ROUte {route_options}

Parameters:

              route_options                                                                     (Required)

              Sets the default options for routing to the printer.

              SS4

              For information about these options, see BASIS Reference, “Op. Sys. System Specifics”
              where Op. Sys. is the name of your operating system.

Prompt:
                    All parameters are optional, do you wish to change any (Y/N)?>

Key Points:
                   Route parameters may be separated by either commas or slashes and values do not
                    have to be quoted unless they contain a comma, slash, or space.
                   Either single or double quotes can be used. Quotes inside the string must be doubled.
                   Parameters can be set any number of times, but only the last value set is used.

Examples:

              SS4

              For examples, see BASIS Reference, “Op. Sys. System Specifics” where Op. Sys. is the
              name of your operating system.




                                                                              Command References  457
               SET/THESaurus_options
Purpose:

               To assign default values to parameters of thesaurus-related commands such as BROWSE
               and FInd. You can display default values using the SHow/THESaurus_options command.

Syntax:

               SET/THESaurus_options
                     {,DROP=YES | NO}
                     {,FORMAT=format}
                     {,HIER_RELations=hierrel}
                     {,LANGuage=lang}
                     {,LEAD_GRAPHics=graphics}
                     {,LIMit=1:20}
                     {,REFerences=NO | YES}
                     {,RELations=relations}
                     {,SAVe_browse=NO | YES}
                     {,THESaurus=thes_name YES | NO}
                     {,TOP_term=NO | YES}
                     {,WAIt=YES | NO}

Parameters:

               DROP=YES | NO                                                                  (Optional)

               Indicates whether the cursor is dropped from its previous thesaurus assignment and
               reestablished according to the criterion of the current BROWSE command. The default is
               YES.


                YES      The cursor is dropped and then reestablished.

                NO       The cursor is maintained according to its previous assignment.

               FORMAT=format                                                                  (Optional)

               Indicates the display format and which relations are to be shown to the user. Format
               options are




458  Command References
ALL              will display all relations for a lead term non-hierarchically. This is the
                 default parameter.

LEAD             will display only the LEAD terms (no relations are displayed).

UP               will display hierarchically relations that have a relation usage type of
                 $GENERAL (for example, Broad term relations).

DOWN             will display hierarchically relations that have a relation usage type of
                 $SPECIFIC (for example, Narrow term relations).

ALPHA            will display relations non-hierarchically using the relation types specified
                 in the RELations parameter.

HIER             will display relations hierarchically using relation types specified in the
                 HIER_RELations parameter.

HIER_RELations=hierrel                                                               (Optional)

Indicates the hierarchical relation types to be displayed: any valid hierarchical relation
name or alias or any hierarchical relation usage ($GENERAL, $SPECIFIC, $NONE).
This parameter is used when FORMAT=HIER. If you enter multiple relations, separate
them with commas and enclose the group of relations in parentheses.

LANGuage=lang                                                                        (Optional)

Indicates the preferred language in which the thesaurus terms will be displayed. Used
with multilingual applications only.

LEAD_GRAPHics=graphics                                                               (Optional)

Indicates codes identifying graphics to be used for displaying the lead term.


0:15     Graphics combinations

B        Blink

I        Intensity         (the graphics default is I)

R        Reverse video

U        Underline




                                                                  Command References  459
               LIMit=1:20                                                                        (Optional)

               Indicates the maximum number of thesaurus terms displayed by the BROWSE command.
               The default is 20.

               REFerences=NO | YES                                                               (Optional)

               Indicates whether the system will display index references for the thesaurus terms
               controlling a field. If you use this parameter, you must also specify the FIELD. The
               default is NO.


               NO       The index references for a specific field are not shown.

               YES      All references for relations, even if the reference is zero, are shown. Result
                        sets can be subsequently created by the COMBINE command.

               RELations=relations                                                               (Optional)

               Indicates the relation types to be displayed: any valid relation name or alias or any
               relation usage ($ALL, $PREFER, $NONPREFER, $SPECIFIC, $GENERAL,
               $INFORMATIVE, $REFERENCE, $COMPOSITE, $COMPONENT, $BASE_LANG,
               $ALT_LANG). This parameter is used when FORMAT=ALPHA.

               SAVe_browse=NO | YES                                                              (Optional)

               The SAVE value indicates whether terms from the BROWSE and MORE commands will
               be saved as the values of global variables. The default is NO.


                NO       The terms, relations, and reference counts are not saved as the values of
                         global variables.

                YES      The terms will be saved in the variables DM_THES_TERM_1,
                         DM_THES_TERM_2, ...etc.

                         The relation names will be saved in variables DM_THES_REL_1,
                         DM_THES_REL_2, ...etc.

                         The number of references will be saved in the variables DM_THES_INFO_1,
                         DM_THES_INFO_2, ...etc.




460  Command References
                        The number of members will be saved in the variables DM_THES_MEM_1,
                        DM_THES_MEM_2, ...etc.

             THESaurus=thes_name YES | NO                                                   (Optional)

             Indicates the name of the thesaurus database and thesaurus in thes_db.thes_name form.
             (For example, THES0.COMPANY.) The Thesaurus Control Record defines the
             appropriate thesaurus to use for a field. The default value is YES.


                 YES    References the thesaurus during FQM commands.

                 NO     Does not reference the thesaurus during FQM commands.

             TOP_term=NO | YES                                                              (Optional)

             Indicates that the command returns only top terms (terms with no broader term relations).
             The default is NO.

             WAIt=YES | NO                                                                  (Optional)

             Indicates whether the system should wait for locked records and resources to become
             available. The default is YES.

Prompts:
                   All parameters are optional.          Do you wish to change any (Y/N)?>

Key Point:
                  If you don‟t execute the SET/THESaurus_options command, the system will use the
                   following default values:

                   THESaurus=
                   LIMIT=20
                   WAIT=YES
                   SAVe_browse=NO
                   DROP=YES
                   REFerence=NO
                   Language=
                   FORMat=All
                   RELations=$ALL
                   HIER_RELations=$NONE
                   LEAD_GRAPHics=I
                   TOP_term=NO



                                                                         Command References  461
Examples:

               Note: The actual output of the commands in the examples below may vary depending
               on the operating system and/or the version of BASIS that you are using.
               1.   To set the default values for the parameters used during Thesaurus manipulation,
                    enter your choices at the prompts.
                    FQM> SET/THES
                    All parameters are optional, do you wish to change any
                    (Y/N)? > Y
                    THESaurus=
                    LIMit= 20
                    WAIT= YES
                    SAVe_browse= NO
                    DROp= YES
                    REFerence= NO
                    LANGuage=
                    FORMat= All
                    RELations= $PREFER
                    HIER_RELations= $NONE
                    LEAD_GRAPHics=
               2.   To display the values you entered, use the SHow/THES command.
                    FQM> SHOW/THES
                       THESaurus             =
                       LIMit                 =   20
                       WAIT                  =   YES
                       SAVe_browse           =   NO
                       DROp                  =   YES
                       REFerence             =   NO
                       LANGuage              =
                       FORMat                =   ALL
                       RELations             =   $PREFER
                       HIER_RELations        =   $NONE
                       LEAD_GRAPHics         =   I




462  Command References
              SET/TYPE_Command                                                     (FQM only)
Purpose:

              To define the characteristics of a TYPE command to be save for later use. Also to
              improve the performance of a proc that executes a TYPE command within a loop.

Syntax:

              SET/TYPE_Command TAG=tag,
                    VIEW_list=view_id | (view_id, view_id,...)
                    ,putlist
                    {,parmlist}
                    {,ERR=errlabel}

Parameters:

              TAG=tag                                                                           (Required)

              A 1- to 32-character identifier that uniquely identifies a saved type command. The
              EXECute/TYPE_COMMAND uses this tag to identify the saved command.

              VIEW_list=view_id | (view_id, view_id,...)                                        (Required)

              Specifies the view(s) to be displayed. If more than 1 view is to be displayed, separate the
              view_ids by commas and enclose the group of them in parentheses.

              putlist                                                                           (Required)

              Specifies the fields and the format in which the fields are displayed.

              parmlist                                                                           (Optional)

              Specifies a list of optional parameters that define such output selections as labels, spacing,
              and statistics. For a list of the parmlist options, see Interactive FQM Commands.

              ERR=errlabel                                                                       (Optional)

              Specifies the label in the proc to branch to if the SET/TYPE_COMMAND fails.

              Note: If any of the specified term IDs are not in the result set, the system considers this
              to be a syntax error because it is caught during the parsing stage. Therefore, the system
              will not branch to the label indicated by the ERR parameter, which handles execution




                                                                              Command References  463
               errors only. In the event of syntax errors, you can have the system transfer control to a
               label indicated by the ON/SYNTAX command.

Key Points:
                   Use SET/TYPE_Command to save the processed form of the TYPE command‟s
                    putlist and parmlist before the loop begins. SET/TYPE_Command eliminates the
                    need to process the putlist and parmlist over again each time the loop executes. This
                    helps the proc run more quickly and efficiently.
                   After the SET/TYPE_Command saves the processed form of the putlist and parmlist,
                    the EXEcute/TYPE_Command can quickly execute the saved TYPE command inside
                    a loop or anywhere else in the proc.
                   You can use SET/TYPE_Command and EXEcute/TYPE_Command instead of any
                    valid TYPE command.

Examples:
               1.   The proc TOP_DOGS finds all employees who earn more than $2,800 a month and
                    displays their employee numbers, names, departments, and salaries. Note that this
                    proc was written to demonstrate SET/TYPE_Command and
                    EXEcute/TYPE_Command. You could produce the same result more efficiently
                    with the following two commands:

                    FIND EMPLOYEE WHERE SALARY>2800 ORDER BY SALARY DESCEND
                    TYPE ENO:>5>,NAME:<20<,DNO:<4<,SALARY:>12.2/DC/C> LABELS=NO
                    FQM> SHOW/PF TOP_DOGS, HEADER=NO
                    SET/TYPE_COMMAND TAG=DISPLAY1,ENO:>5>,NAME:<20<, +
                       DNO:<4<,SALARY:> 12.2/DC/C>,VIEW=EMPLOYEE, +
                       LABELS=NO,BUFFER=A
                    FIND EMPLOYEE WHERE SALARY>2800 ORDER BY SALARY DESCEND
                    ACQUIRE/PV MEMBERS N1=MEM
                    FOR COUNT=1,MEM
                       GET/VIEW[0,COUNT]EMPLOYEE@A
                       EXECUTE/TYPE_COMMAND TAG=DISPLAY1
                    END_FOR
                    FQM> @TOP_DOGS
                       Result set 1 contains 5 references to 5 members.

                    1001           DAVIS, JOE                          100           $8,000.00
                    10040          KUNCHAL, KURT                       501           $3,944.00
                    10060          STEIN, MINDY                        601           $2,902.00
                    10028          WILLIAMS, RHONDA                    601           $2,834.00
                    10086          GUSTAFSON, RUSSELL                  501           $2,814.00
               2.   The proc RAISE gives a 10% raise to all employees who have a given job title. The
                    proc prompts the user for a job title and increases the salary of all employees with the
                    specified job. The proc also displays the employee number, name, and new monthly
                    pay of each employee who received a raise.



464  Command References
FQM> SHOW/PF RAISE, HEADER=NO
SET/TYPE_C TAG=PAY_FORMAT1,ENO:>5>,NAME,SALARY*1.10, +
   SPACING=5,VIEW=EMPLOYEE,LABELS=NO,BUFFER=A
*
INQUIRE/PV JOB, 'Enter the job title>'
SET/PV JOB = $STRING(JOB)
FIND EMPLOYEE WHERE JOB=!JOB!
ACQUIRE/PV MEMBERS N1=MEM
START/TRANSACTION PW=EMPLOYEE
*
FOR COUNT=1,MEM
   GET/VIEW[0,!COUNT!]EMPLOYEE
   EXECUTE/TYPE TAG=PAY_FORMAT1
   SET/PV SAL = SAL*1.10
   ASSIGN/FIELD [0,!COUNT!]EMPLOYEE.SALARY=!SAL!
END_FOR
END_TRANSACTION

FQM> @RAISE
Enter the job title> Vice-President
   Result set 3 contains 5 references to 5 members.

10008         WHANG, BERNARD            3012.90
10028         WILLIAMS, RHONDA          3117.40
10029         LIN, ANN                  2996.40
10060         STEIN, MINDY              3192.20
10090         ROBINSON, JOHN            2891.90
FQM>




                                          Command References  465
               SET/TYpe_options
Purpose:

               To assign default values to parameters of the TYpe command. Use SHow/TYpe_options
               to see the current defaults.

Syntax:

               SET/TYpe_options
                     {,ABSent='absstrg'}
                     {,APPend=YES | NO}
                     {,ASCENding=YES | NO}
                     {,BUFfer=letter}
                     {,COUnt=NO | YES}
                     {,DATa=YES | NO}
                     {,DOC_Boundary=None | Hard | Soft}
                     {,FID=* | fid}
                     {,FILE | FD=filedescriptor}
                     {,FOOTing='literal' | (putlist)}
                     {,FOOTING_LENgth=* | 0:100}
                     {,HEADing | TITle='literal' | (putlist)}
                     {,HEADING_LENgth | TITLE_LENgth=* | 0:100}
                     {,LABel=YES | NO}
                     {,LENgth | PAGe=0:1000000000}
                     {,MAXimum=NO | YES}
                     {,MEAn | AVErage=NO | YES}
                     {,MEMbers=* | member}
                     {,MINimum=NO | YES}
                     {,PAUse=NO | YES}
                     {,PRESENTER=presenter}
                     {,QREAD=YES | NO}
                     {,SCROLL=STYLE | NO | YES}
                     {,SCROLL_CLEAR=NO | YES}
                     {,SCROLL_DEFAULT=NEXT REFERENCE | scroll_cmd | RESOLicit}
                     {,SCROLL_LINES=15 | number_of_lines}
                     {,SCROLL_MARGIN=0 | n}
                     {,SCROLL_Position=DOCUMENT or SECTION granularities}
                     {,SEC_Boundary=None | Hard | Soft}
                     {,SECtion=REFerences | ALL | *}
                     {,SET=0 | setnumber}
                     {,SKIp=1 | 0:100}
                     {,SPAcing=2 | 0:15}



466  Command References
                       {,TABular=STYLE | NO | YES}
                       {,TOTal | SUM=NO | YES}
                       {,TRUncated='trstrg'}
                       {,UNIques=NO | YES}
                       {,USETab=NO | YES}
                       {,WAIt=NO | YES}
                       {,WIDth=80 | 1:512}
                       {,WRAp=YES | NO}

Parameters:

              ABSent='absstrg'                                                                  (Optional)

              Indicates the 1 to 15 character string displayed when a field value is absent from a record.
              The default is a space (' ').

              APPend=YES | NO                                                                   (Optional)

              Indicates whether the output is appended to an existing file (if one exists). If the FILE
              parameter is not used, the APPend parameter is ignored. The default is YES.


              YES       The output is appended to an existing file.

              NO        The output is typed to a new file.

              ASCENding=YES | NO                                                                (Optional)

              Indicates the order in which to display the members of the result set. The default is YES.


              YES       Members are displayed in ascending order.

              NO        Members are not displayed in ascending order.

              BUFfer=letter                                                                     (Optional)

              Indicates whether what is displayed is a record in a user buffer or the members of a result
              set. The default is a space (' ') and the members of a result set are displayed. If a letter
              A:H of a user buffer is specified, only one record is displayed.




                                                                             Command References  467
               COUnt=NO | YES                                                                 (Optional)

               Indicates whether the number of present values for each column is computed and typed.
               The default is NO. If TABular=NO, COUnt=YES is ignored.


               NO        Non-absent values are not counted.

               YES       Non-absent values are counted and displayed.

               DATa=YES | NO                                                                  (Optional)

               Indicates whether individual members of a result set are displayed. The default is YES.


               YES       The individual members are displayed.

               NO        The individual members are not displayed. The statistics specified are
                         displayed. If statistics are not specified, all (count, maximum, mean,
                         minimum, and total) are displayed.

               DOC_Boundary=None | Hard | Soft                                                (Optional)

               Defines what happens when a document boundary is encountered during NEXT/PRIOR
               scrolling of LINE/UNIT/WINDOW/PAGE/REFERENCE granularities. The default is
               None.


               None        The next/prior document is immediately shown without any message or
                           prompt.

               Hard        The boundary is not crossed and an end message is displayed.

               Soft        You must confirm the boundary crossing. A prompt is displayed asking you
                           to confirm the crossing, such as:

                           Do you want to display the next document? (Yes or No)>

                           Do you want to display the prior document? (Yes or No)>

                           If you confirm the crossing, the next/prior document is shown. If you cancel
                           the crossing, you will see a message.




468  Command References
FID=* | fid                                                                        (Optional)

Indicates a file identifier for the file the TYpe command uses as the output file. If used,
the FID must reference a file opened by an ;OPen/FIle command. If a file is not specified
and FID=' ', then the data is printed in the current output file. The default is ' '. Use
SHOW/FID to see the open files.

FILE | FD= filedescriptor                                                          (Optional)

Indicates a file descriptor for the file that the TYpe command creates or appends and uses
as the output file. If not supplied, the default output file (usually displayed to a terminal)
is used.

FOOTing='literal' | (putlist)                                                      (Optional)

Indicates a title that you surround with single quotation marks (') or a putlist that
comprises the footing displayed at the bottom of each page of information. (See the
TYpe command reference for more information about putlist.) The default is a space. If
LENGTH=0, FOOTING_LENGTH=0, or SCROLL=YES, the FOOTING parameter is
ignored.

FOOTING_LENgth=* | 0:100                                                           (Optional)

Indicates the length of the page footing. The default is a length calculated from the size
of the footing.

HEADing | TITle='literal' | (putlist)                                              (Optional)

Indicates a title that you surround with single quotation marks (') or a putlist that
comprises the heading displayed at the top of each page of information. (See the TYpe
command reference for more information about putlist.) The default is a space. If the
LENGTH=0, HEADING_LENGTH=0, TITLE_LENGTH=0, or SCROLL=YES, the
HEADING (also called TITLE) parameter is ignored.

HEADING_LENgth | TITLE_LENgth=* | 0:100                                            (Optional)

Indicates the length of the page heading. The default is a length calculated from the size
of the heading.

LABel=YES | NO                                                                     (Optional)

Indicates whether the labels are used as column headings. The label is a label supplied on
the TYpe command (/'label'), a default label (from SET/PICture or the DDL), or a derived
label (for an expression). The default is YES.




                                                                Command References  469
               YES       Labels are displayed.

               NO        Labels are not displayed.

               LENgth | PAGe=0:1000000000                                                    (Optional)

               Indicates the length in lines of each page. If LENgth=0, lines are not counted and PAUse,
               TITle, HEADing and FOOTing parameters are ignored. The default is 0.

               MAXimum=NO | YES                                                              (Optional)

               Indicates whether a maximum value for each column is displayed. The default is NO. If
               TABular=NO, MAXimum=YES is ignored.


               NO        Maximum values are not displayed.

               YES       The maximum value of each column is displayed.

               MEAn | AVErage=NO | YES                                                       (Optional)

               Indicates whether a mean value (average) is computed and displayed for each column.
               The default is NO. If TABular=NO, MEAn=YES is ignored.


               NO        Mean values are not displayed.

               YES       A mean value is displayed for each column.

               MEMbers=* | member | (member{,member}0:*)                                     (Optional)

               Indicates which members of a result set are displayed. Members is in one of the
               following formats:


               *           All members are displayed.

               m:n         Members m through n are displayed.

               m:*         Members m through the last member are displayed.

               m           Member m is displayed.




470  Command References
(m,m)       Member numbers specified in a list must be enclosed in parentheses and
            separated by commas.

The default is *.

MINimum=NO | YES                                                                (Optional)

Indicates whether a minimum value of each numeric column is displayed. The default is
NO. If TABular=NO, MINimum=YES is ignored.


YES       The minimum value of each column is displayed.

NO        Minimum values are not displayed.

PAUse=NO | YES                                                                  (Optional)

Indicates whether the TYpe command prompts with “Do you want to stop (Y/N)? >” after
each page is typed when LENgth is more than 0. The default is NO.


NO        The TYpe command displays the requested members without stopping.

YES       The TYpe command issues the prompt after each page displayed.

PRESENTER=presenter                                                             (Optional)

Indicates the name of the presenter. The presenter specified must be defined in the style
guide.

QREAD=YES | NO                                                                  (Optional)

Indicates whether or not records stored in the Queue Area are to be displayed for TYpe
commands. The default is YES.


YES       The record from the Queue Area is displayed if it is on READY status.
          Otherwise, the database record is displayed.

NO        Only database records are displayed.




                                                              Command References  471
               SCROLL=STYLE | NO | YES                                                             (Optional)

               Indicates whether or not interactive scroll commands can be entered to help you navigate
               through the text stream field. The default is STYLE.


               STYLE       When you use this setting, you will get scrolling whenever a Long Text
                           field is included in the typelist. If you want to scroll a field that is not Long
                           Text, then Scroll=YES.

               NO          Interactive scroll commands cannot be entered.

               YES         Interactive scroll commands can be entered regardless of the contents of
                           your putlist. Scroll prompts are usually received from the terminal, but can
                           be received from a proc file if SET/MODE INTERactive_prompt=NO.
                           The scroll prompt will change, depending on whether notes or reveal
                           markup elements are available for the new lines displayed on the screen
                           since the last scroll prompt. These are the possible prompts:

                           Enter scroll command>

                           Enter scroll command (NOTes available)>

                           Enter scroll command (REVeal)>

                           Enter scroll command (NOTes, REVeal)>


               SCROLL_CLEAR=NO | YES                                                               (Optional)

               Indicates whether or not to clear the screen after each scrolling command is entered. The
               default is NO. For this parameter to be processed, the SCROLL parameter value must be
               YES or STYLE.


               NO       The screen is not cleared after each scrolling command.

               YES      The screen is cleared after each scrolling command.

               SCROLL_DEFAULT=NEXT REFERENCE | scroll_cmd | RESOLicit                              (Optional)

               Defines the default scroll command to be executed when a [RETURN] (i.e., a zero-length
               input string of zero) is entered as a response to an interactive scrolling command. The
               default is NEXT REFERENCE. For this parameter to be processed, the SCROLL




472  Command References
parameter value must be YES or STYLE. (For more information about scroll_cmd, see
“Scroll_cmd Syntax” for the TYPE command.)

SCROLL_LINES=15 | number_of_lines                                                     (Optional)

Indicates the number of lines of text stream to be displayed with each scrolling command.
For this parameter to be processed, the SCROLL parameter value must be YES or
STYLE. The default is 15.

SCROLL_MARGIN=0 | n                                                                   (Optional)

Indicates the column where the text stream output begins to be displayed. The default is
0, which means that the text begins one column after the columns reserved for marking
references and numbering lines. The value of n can be an integer from 1 to the column
width of the screen. For this parameter to be processed, the SCROLL parameter value
must be YES or STYLE and the field must be a text stream (defined with
USAGE=TEXT_STREAM) field.

SCROLL_Position=DOCUMENT or SECTION granularities                                     (Optional)

This parameter allows you to control the display of records when you scroll through them
by using the DOCUMENT or SECTION granularities. For a list of these granularities,
see the “TYPE” command later in this chapter.

If you want the display to start at the first line of a document or section, enter:
            TYPE TEXT, SCROLL_P=FIRST_Line

If you want the display to start at the first reference (search term) in a document or
section, enter:
            TYPE TEXT, SCROLL_P=FIRST_Reference

The default is FIRST_Reference.

SEC_Boundary=None | Hard | Soft                                                       (Optional)

Defines what happens when a section boundary is encountered during NEXT/PRIOR
scrolling of LINE/UNIT/WINDOW/PAGE/REFERENCE granularities. The default is
None.


None        The next/prior section is immediately shown without any message or prompt.

Hard        The boundary is not crossed and an end message is displayed.




                                                                 Command References  473
               Soft        You must confirm the boundary crossing. A prompt is displayed asking you
                           to confirm the crossing such as:

                           Do you want to display the next section? (Yes or No)>

                           Do you want to display the prior section? (Yes or No)>

                           If you confirm the crossing, the next/prior section is shown. If you cancel
                           the crossing, you will see a message.

               SECtion=REFerences | ALL | *                                                        (Optional)

               Indicates whether or not to display sections containing references.


               REFerences         Display only sections that contain references. REFerences is the
                                  default.

               ALL | *            Display all sections whether or not they contain references.

               SET=0 | setnumber                                                                   (Optional)

               Indicates the number of the result set to be displayed. Set number is in one of the
               following formats.


               0         Members of the last active result set are displayed.

               -m        Members of result set number “last active result set -m” are displayed.

               m         Members of result set number m are displayed.

               SKIp=1 | 0:100                                                                      (Optional)

               Indicates how many blank lines should be skipped before data is printed. The default is 1.

               SPAcing=2 | 0:15                                                                    (Optional)

               Indicates how many spaces ($Xn) are displayed between columns where no spacing is
               specified. Valid values are from 0 to 15. The default is 2.

               TABular=STYLE | YES | NO                                                            (Optional)




474  Command References
Indicates whether the field values are displayed in columnar format or each field value
begins on a new line. The default is STYLE.


STYLE        Determines from the result set what tabular style to use such as TAB=NO
             for a text stream field or TAB=YES for conventional text.

YES          Field values are displayed in a columnar format.

NO           Field values are displayed with each value beginning on a different line.

TOTal | SUM=NO | YES                                                                (Optional)

Indicates whether a total (sum) is computed and displayed for each column. The default
is NO. If TABular=NO, TOTal=YES is ignored.


NO        Totals for each column are not displayed.

YES       Totals for each column are displayed.

TRUncated='trstrg'                                                                  (Optional)

Indicates a 1 to 8 character string printed as the last few characters of a data value that has
more characters than the specified space allows. The default is '...'.

UNIques=NO | YES                                                                    (Optional)

Indicates whether all members are displayed even if the field values are exactly the same
as the field values displayed on the previous line. To be effective, the result set must be
sorted. The default is NO. If TABular=NO, UNIques=YES is ignored.


NO        Fields are displayed for all members regardless of duplicates.

YES       Only unique records are displayed. Duplicates of those already displayed are
          suppressed.




                                                                Command References  475
               USETab=NO | YES                                                                  (Optional)

               Allows you to control the display of tabs in a record. If you want to keep the tab spacing,
               enter:
                           TYPE TEXT, USET=YES

               The system replaces each tab with the appropriate number of spaces to reach the next tab
               setting. The system uses a tab increment of 8; thus, the tab settings are columns 8, 16, 24,
               32, etc.

               For example, if a record has a tab in column 19, the system replaces the tab with 5 blank
               spaces to reach the next tab setting, which is 24.

               If you do not want to keep the tab spacing when you display a record, enter:
                           TYPE TEXT, USETAB=NO

               The system replaces each tab with a single blank space.

               The default is NO.

               WAIt=NO | YES                                                                    (Optional)

               Indicates whether the TYpe command waits for resources locked by other users to
               become available. The default is NO.


               NO       The TYPE command issues a message indicating that the member is not
                        available and it does not wait.

               YES      The TYPE command waits for resources locked by other users to become
                        available.

               WIDth=80 | 1:512                                                                 (Optional)

               Indicates the character width of a page. The page width can be from 1 to 512 characters.
               The default is 80.

               WRAp=YES | NO                                                                    (Optional)

               Indicates whether lengthy information wraps to the next display line. The default is YES.


               YES      Lengthy information is wrapped to the next line.



476  Command References
              NO       Only the characters of information that fit within the page width are displayed.
                       The rest are truncated.


Prompts:
                   All parameters are optional.            Do you wish to change any
                   (Y/N)? >

Key Points:
                  If the SET/Type_options command is not used, default parameters used by the TYpe
                   are as follows:


                    ABSent                     =

                    APPend                     = YES

                    ASCENding                  = YES

                    BUFfer                     =

                    COUnt                      = NO

                    DATa                       = YES

                    DOC_Boundary               = NONE

                    FID                        =

                    FILE                       =

                    FOOTing                    =

                    FOOTING_LENgth             =0

                    HEADing                    =

                    HEADING_LENgth             =0

                    LABel                      = YES

                    LENgth                     =0

                    MAXimum                    = NO



                                                                            Command References  477
                   MEAn             = NO

                   MEMbers          = 1:2000000000

                   MINimum          = NO

                   PAUse            = NO

                   PRESenter        = SYS_PLAIN_MONO

                   QREAD            = YES

                   SCROLL           = STYLE

                   SCROLL_Clear     = NO

                   SCROLL_Default   = Next Reference

                   SCROLL_Lines     = 15

                   SCROLL_Margin    =0

                   SECtion          = REF

                   SEC_Boundary     = NONE

                   SET              =0

                   SKIp             =1

                   SPAcing          =2

                   TABular          = STYLE

                   TOTal            = NO

                   TRUncated        = ...

                   UNIques          = NO

                   USETab           =NO

                   WAIt             = NO




478  Command References
                  WIDth                      = 80

                  WRAp                       = YES

                The SET/TYpe_options command often is used in login procedures to set the
                 appropriate default values for a user or a specific database. If a SET/TYpe_options
                 command is used within a login procedure, it is likely that the default parameter
                 values listed above will not apply.
                You can use the SHOW/TYpe_options command to view the parameter values for a
                 specific work session.

Examples:

            Note: The actual output of the commands in the examples below may vary depending
            on the operating system and/or the version of BASIS that you are using.
            1.   You can enter values for parameters by responding to prompts (a.) or by entering
                 parameters and their values with the SET/TYpe command (b.). When you enter
                 [RETURN] the default value is used.
            a.   FQM> SET/TY
                 All parameters are optional.            Do you wish to change any
                 (Y/N)?> Y
                 WIDth= 80
                 LABel= YES
                 WRAp= YES
                 PAUse= NO
                 TABular= STYLE
                 UNIques= NO
                 DATa= YES
                 TOTal= NO
                 MINimum= NO
                 MAXimum= NO
                 MEAn= NO
                 COUnt= NO
                 WAIt= NO
                 APPend= YES
                 LENgth= 0
                 HEADing=
                 HEADING_LENgth= 0
                 FOOTing=
                 FOOTING_LENgth= 0
                 SET= 0
                 MEMbers= 1:2000000000
                 BUFfer=
                 FID=
                 FILE=
                 SPAcing= 2
                 ABSent=
                 TRUncated=
                 SKIp= 0



                                                                         Command References  479
                    ASCENding= YES
                    SCROLL= STYLE
                    SCROLL_Lines= 15
                    SCROLL_Margin= 0
                    SCROLL_Clear= NO
                    SCROLL_Default= NEXT REFERENCE
                    QREAD= YES
                    PRESenter= SYS_PLAIN_MONO
                    DOC_Boundary= None
                    SEC_Boundary= None
                    SECtion= REF
               b.   FQM> SET/TY WID=80,LAB=NO,DAT=YES,TOT=NO,APP=NO,LEN=5

               2.   The TYpe command uses the parameter settings of the SET/TYpe_options command.
                    Because the first TYpe command (a.) uses the current defaults, TOTAL=NO and
                    MAXIMUM=NO, no statistics are displayed. The second TYpe command (b.) uses
                    the defaults defined by the SET/TYpe_options command, TOTAL=YES and
                    MAXIMUM=YES.
               a.   FQM> TYPE NAME,SALARY,COMM
                    WARD, DANA       $2,361.00
                    GUSTAFSON,       $2,814.00
                    RUSSELL
                    LOVE, ALLEN        $953.00
                    COHEN, SUAN      $1,038.00
                    MCNALLY, WENDY   $1,503.00
                    SHELTON,         $1,166.00
                    JOSHUA
                    SABOE, MIKE      $1,317.00
                    LAPP, RUSSELL    $1,349.00
                    KANG, SAM          $933.00
                    HELMICK, CURT    $1,448.00          $390.00
                    KUNCHAL, KURT    $3,944.00
                    YEH, HUEI        $1,310.00
               b.   FQM> SET/TYPE TOTAL=YES,MAXIMUM=YES
                    FQM> TYPE NAME,SALARY,COMM
                    WARD, DANA       $2,361.00
                    GUSTAFSON,       $2,814.00
                    RUSSELL
                    LOVE, ALLEN        $953.00
                    COHEN, SUAN      $1,038.00
                    MCNALLY, WENDY   $1,503.00
                    SHELTON,         $1,166.00
                    JOSHUA
                    SABOE, MIKE      $1,317.00
                    LAPP, RUSSELL    $1,349.00
                    KANG, SAM          $933.00
                    HELMICK, CURT    $1,448.00    $390.00
                    KUNCHAL, KURT    $3,944.00
                    YEH, HUEI        $1,310.00
                                       $20,136.00         Total
                                        $3,944.00         Max




480  Command References
3.   Because the first TYpe command (a.) uses the ABSENT parameter value of '', a null
     string is displayed when the commission field value is absent from the view record.
     The second TYpe command (b.) uses the ABSENT='N/A' defined by
     SET/TYpe_options.
a.   FQM> TYPE NAME,COMM
     WARD, DANA
     GUSTAFSON,
     RUSSELL
     LOVE, ALLEN
     COHEN, SUAN
     MCNALLY, WENDY
     SHELTON,
     JOSHUA
     SABOE, MIKE
     LAPP, RUSSELL
     KANG, SAM
     HELMICK, CURT     $390.00
     KUNCHAL, KURT
     YEH, HUEI
b.   FQM> SET/TYPE ABSENT='N/A'
     FQM> TYPE NAME,COMM
     WARD, DANA            N/A
     GUSTAFSON,            N/A
     RUSSELL
     LOVE, ALLEN           N/A
     COHEN, SUAN           N/A
     MCNALLY, WENDY        N/A
     SHELTON,              N/A
     JOSHUA
     SABOE, MIKE           N/A
     LAPP, RUSSELL         N/A
     KANG, SAM             N/A
     HELMICK, CURT     $390.00
     KUNCHAL, KURT         N/A
     YEH, HUEI             N/A




                                                             Command References  481
               SET/UC
Purpose:

               To define a user command. Use the SHow/UC command to display the current user
               commands, DELete/UC to delete user commands, and PERFORM to ignore set user
               commands.

Syntax:

               SET/UC usercommand=string

Parameters:

               usercommand                                                                    (Required)

               Specifies the l-to-32 character name to be entered as the equivalent of the command.

               string                                                                         (Required)

               Indicates the command or part of the command that is executed when the usercommand is
               entered.

Prompts:
                   usercommand=string:

Key Points:
                  A user command is an abbreviation for part or all of a BASIS command. User
                   commands are especially useful for abbreviating long commands that contain many
                   parameters.
                  Do not use a BASIS command or command abbreviation as the name of a user
                   command. If, for example, you use FIND as the user command for FIND
                   EMPLOYEE WHERE JOB = 'Programmer', the system would interpret a command
                   like
                   FIND DEPENDENT

                   as
                   FIND EMPLOYEE WHERE JOB = 'Programmer' DEPENDENT




482  Command References
   Do not use the following words as user commands:


    BREAK               BREAK_IF           BREAKIF             CASE

    DEFAULT             ELSE               ELSE_IF             ELSEIF

    END_FOR             ENDFOR             END_IF              ENDIF

    END_LOOP            ENDLOOP            END_SELECT          ENDSELECT

    END_WHILE           ENDWHILE           FOR                 IF

    LOOP                NEXT               NEXT_IF             NEXTIF

    REPEAT              SELECT             UNTIL               WHILE

   When you submit a command, the system compares the characters that precede the
    first special character (such as a blank or a slash) in the command with the user
    commands. If the characters match a user command, the system executes that form
    of the command. If the characters do not match a user command, the system
    compares the characters with the standard BASIS commands.
   You can define a user command as a command (SHOW) or a command and its
    qualifier (SHOW/UC), or a command and its parameters (TYPE PAGE=24,
    PAUSE=YES). You cannot define a user command as a qualifier only (/UC) or as an
    explain topic (?SHOW).
   The user commands remain in effect for the current session unless they are deleted or
    redefined.
   To avoid having to issue a SET/UC command for each frequently-used user
    command in each session, place these SET/UC commands in your user login proc.
   The PERFORM command causes the system to ignore all user commands currently
    in effect. In the preceding example, PERFORM FIND DEPENDENT would have
    executed the FIND command properly.




                                                            Command References  483
Examples:
               1.   You can respond to SET/UC prompts (a.) or enter the user command and string with
                    the SET/UC command (b.). The command F1 produces the same results as the
                    command FIND EMPLOYEE.
               a.   FQM> SET/UC
                    usercommand=string: F1=FIND EMPLOYEE

               b.   FQM> SET/UC F1=FIND EMPLOYEE

               2.   User commands F1 and F2 are defined as a variety of the FIND command.
                    FQM> SET/UC F1=FIND EMPLOYEE
                    FQM> SET/UC F2=FIND EMPLOYEE WHERE DNO=101

               3.   User commands can be defined as a complete command (e.g., DB=SHOW/DB) or as
                    partial commands (e.g., OPENR=OPEN/DB INTENT=READ). Additional
                    parameters can be included with a user command (e.g., OPENR TOUR.ALL,
                    WAIT=NO).
                    FQM> SET/UC DB=SHOW/DB
                    FQM> SET/UC OPENR=OPEN/DB INTENT=READ
                    FQM> SET/UC OPENU=OPEN/DB INTENT=UPDATE
                    FQM> OPENR TOUR.ALL,WAIT=YES
                    FQM> OPENU ACME0.FQMA,WAIT=NO
                    FQM> DB
                    The open database models are:

                    Intent      Version     Database.Mode         Kernel    Primary Name
                    ------      -------     --------------        ------    ------------
                    Read         0          <TOUR.ALL>            DMKA2     TOUR
                    Update       0          <ACME0.FQMA>          DMKA1     ACME0   (default)
               4.   The SET/UC command can define abbreviated forms of the frequently used
                    commands such as SET/MODE TRACE=YES and SET/MODE TRACE=NO.
                    FQM> SET/UC TRACE=SET/MODE TRACE=YES
                    FQM> SET/UC NOTRACE=SET/MODE TRACE=NO
                    FQM> TRACE
                    FQM> FIND EMPLOYEE WHERE SALARY GT 3000
                       Result set 1 contains 2 references to 2 members.
                    FQM> NOTRACE
                    FQM> SHOW/PF TRACE,HEADER=NO
                    FIND EMPLOYEE WHERE SALARY GT 3000
                    NOTRACE




484  Command References
5.   You can ignore user command substitution and execute the actual BASIS command
     by using the PERFORM command. When the PERFORM command precedes the
     user command, the BASIS system uses the system command rather than the user
     command.
     FQM> SET/UC FIND=FIND EMPLOYEE WHERE DNO=101
     FQM> PERFORM FIND DEPARTMENT WHERE DNO=101

6.   You can see all of the defined user commands and their equivalent strings using the
     SHow/UC command.
     FQM> SHOW/UC
        DB = SHOW/DB
        F1 = FIND EMPLOYEE
        F2 = FIND EMPLOYEE WHERE DNO=101
        FIND = FIND EMPLOYEE WHERE DNO=101
        NOTRACE = SET/MODE TRACE=NO
        OPENR = OPEN/DB INTENT=READ
        OPENU = OPEN/DB INTENT=UPDATE
        TRACE = SET/MODE TRACE=YES
7.   You can delete user commands by using the DELete/UC command.
     FQM> DELETE/UC F1
     FQM> SHOW/UC
        DB = SHOW/DB
        F2 = FIND EMPLOYEE WHERE DNO=101
        FIND = FIND EMPLOYEE WHERE DNO=101
        NOTRACE = SET/MODE TRACE=NO
        OPENR = OPEN/DB INTENT=READ
        OPENU = OPEN/DB INTENT=UPDATE
        TRACE = SET/MODE TRACE=YES




                                                             Command References  485
               SHow
Purpose:

               To list the available SHow command options. For specific descriptions, see the
               individual SHow commands described in the following pages.

Syntax:

               SHow {/showoption}

Parameters:

               /showoption                                                                      (Optional)

               Indicates one of the following options:


               /Buffers                      /DB                        /DDB

               /Defaults                     /DIRectory                 /FID

               /File                         /GV                        /HOST_variable

               /LIBrary                      /Look_cursors              /MESsage

               /Mode                         /PD                        /PF

               /PICture                      /PLibrary                  /PL /Directory
                                                   1                          1
               /PV                           /RD                        /RF

               /ROUTe                        /SD                        /Sets

               /SF                           /THES_CURsors              /THESaurus_options

               /TIME                         /TYPE_Command              /Type_options

               /UC

                     1
                         For descriptions of SHOW/RD and SHOW/RF, see Reports.




486  Command References
Prompts:

           None.

Example:

           Note: The actual output of the commands in the examples below may vary depending
           on the operating system and/or the version of BASIS that you are using.

           The SHow command lists the available options.
               FQM> SHOW

               SHOWS
               There are several forms of the FQM SHow command:

               SHow                      -   Lists the available SHow commands (see below).
               SHow/Buffers              -   Lists the view types residing in user buffers.
               SHow/DB                   -   Lists the open database models.
               SHow/DDB                  -   Lists information from the DDB.
               SHow/Defaults             -   Lists the default parameter settings.
               SHow/DIRectory            -   Lists the files in a directory.
               SHow/FID                  -   Lists the open files.
               SHow/File                 -   Lists the contents of a file.
               SHow/GV                   -   Lists the values of the specified global
                                             variables.
               SHow/HOST_variable        -   Lists the value of the specified host
                                             variable.
               SHow/LIBrary              -   Lists the search order of the libraries for a
                                             library set.
               SHow/Look_cursors         -   Lists information about the active look
                                             cursors.
               SHow/MESsage              -   Shows an error message.
               SHow/Mode                 -   Lists the current values of the mode
                                             parameters.
               SHow/PD                   -   Lists the proc files in a directory.
               SHow/PF                   -   Lists the contents of a proc file.
               SHow/PICture              -   Lists the default output picture for the
                                             fields.
               SHow/PL/Directory         -   Lists the names of the procs in the specified
                                             library file.
               SHow/PL/P                 -   Shows the contents of the specified proc.
               SHow/PV                   -   Lists the values of the specified proc
                                             variables.
               SHow/RD                   -   Lists the report files in a directory.
               SHow/RF                   -   Lists the report files.
               SHow/ROUTe                -   Lists the routing file for printing.
               SHow/SD                   -   Lists the result set files in a directory.
               SHow/Sets                 -   Lists the ids for the active result sets.
               SHow/SF                   -   Lists the result set files.
               SHow/THES_CURSors         -   Shows information about active Browse
                                             thesaurus cursors.
               SHow/THESaurus_options -      Shows information about active Browse
                                             thesaurus cursors.
               SHow/TIME                 -   Shows the time of day and the SRU count.
               SHow/TYPE_Command         -   Lists the definitions of all cached type
                                             commands.
               SHow/Type_options         -   Lists the TYpe option settings.
               SHow/UC                   -   Lists the values of specified commands.




                                                                   Command References  487
488  Command References

				
DOCUMENT INFO
Shared By:
Categories:
Stats:
views:16
posted:7/3/2011
language:English
pages:162