home *** CD-ROM | disk | FTP | other *** search
/ ftp.robelle3000.ai 2014 / 2014.06.ftp.robelle3000.ai.tar / ftp.robelle3000.ai / manuals / text / xplib.txt < prev   
Text File  |  2007-12-20  |  67KB  |  1,877 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                                            ______ _______ ___
  19.                                                            XPRESS Version 3.2
  20.  
  21.  
  22.  
  23.  
  24.                                                    __________ __________ ____
  25.                                                    Affordable Electronic Mail
  26.                                                               ___ ___ __ ____
  27.                                                               for the HP 3000
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.                                                      ______ _________ _______
  38.                                                      Xpress Intrinsic Library
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.                                             _______ _________ __________ ____
  52.                                             Robelle Solutions Technology Inc.
  53.                                                    ____ ___ _______ _____ ___
  54.                                                    7360 137 Street, Suite 372
  55.                                                  _______ ____  ______ ___ ___
  56.                                                  Surrey, B.C.  Canada V3W 1A3
  57.  
  58.                                                     __________  _____________
  59.                                                     Toll-free:  1.888.robelle
  60.                                                              ________________
  61.                                                              (1.888.762.3553)
  62.                                                          ______  ____________
  63.                                                          Phone:  604.501.2001
  64.                                                            ____  ____________
  65.                                                            Fax:  604.501.2003
  66.  
  67.                                                  _______  ___________________
  68.                                                  E-mail:  support@robelle.com
  69.                                                         ____  _______________
  70.                                                         Web:  www.robelle.com
  71.  
  72.  
  73.  
  74.                                                                     ____ ____
  75.                                                                     July 1996
  76.  
  77.  
  78.  
  79.            Program and Manual Copyright  Robelle  Solutions  Technology  Inc.
  80.            1990-2007
  81.  
  82.  
  83.                                                                       ___
  84.            Permission  is  granted  to  reprint  this  document  (but not for
  85.            profit), provided that copyright notice is given.
  86.  
  87.  
  88.            XPRESS, QEDIT and SUPRTOOL are  trademarks  of  Robelle  Solutions
  89.            Technology Inc.
  90.  
  91.  
  92.  
  93.  
  94.            The  following  names  and  marks  are companies and trademarks of
  95.            their respective owners, which designate  companies  and  products
  96.            not   provided  by  or  associated  with  Robelle  or  its  XPRESS
  97.            electronic mail, QEDIT  editor,  and  SUPRTOOL  database  handyman
  98.            products.
  99.            HP,  HP  3000,  IMAGE,  LaserJet, MPE, and VPLUS are trademarks of
  100.            Hewlett-Packard Company.
  101.  
  102.                                                                             1
  103.  
  104.  
  105.  
  106.  
  107.     _______ _   _____
  108.     Chapter 1   XPLIB
  109.  
  110.  
  111.                 _  ____________
  112.                 ⁿ  Introduction
  113.                 _  ________ _____________
  114.                 ⁿ  Printing Documentation
  115.  
  116.  
  117.     ____________
  118.     Introduction
  119.  
  120.            Welcome to version 3.2 of  the  Xpress  Intrinsic  Library.   This
  121.            intrinsic library provides a set of subroutines that can be called
  122.            from any 3GL programming language.  These routines  provide  these
  123.            functions:
  124.  
  125.                                                  __ ______  _____________
  126.            ⁿ  You  can  obtain  the  number  of  In Basket, Bring-Forward, or
  127.               ________ _____
  128.               Bulletin Board messages for an Xpress user.
  129.  
  130.            ⁿ  You can discover whether an Xpress user exists.
  131.  
  132.            ⁿ  You can specify the Xpress user  name  and  user  password  for
  133.               subsequent invocations of Xpress.
  134.  
  135.  
  136.     ________ _____________
  137.     Printing Documentation
  138.  
  139.                                                              ______ _________
  140.            To  print  extra  copies  of  this  user  manual (Xpress Intrinsic
  141.            _______
  142.            Library), run the Printdoc program.
  143.  
  144.                 :run printdoc.pub.robelle;info="xplib.doc.robelle"
  145.  
  146.            Printdoc is menu-driven, and very easy to use.  Printdoc asks  you
  147.            for  information,  and if you are not sure of your answer, you can
  148.            ask for help by typing a question mark (?) and pressing the Return
  149.            key.  Printdoc supports all types of LaserJet printers and regular
  150.            line printers.  You can also print documentation other  than  user
  151.            manuals (for example, change notices), if you know the filename.
  152.  
  153.            Printdoc uses a message catalog, and requires Prose version 3.1 or
  154.            later.  It will look for  these  files  in  the  same  account  as
  155.            Printdoc.    Also,   Printdoc  will  only  correctly  print  Prose
  156.            documents that use the Output JCWs and the Prose  If  commands  to
  157.            choose the output device.
  158.  
  159.            Note  that the table of contents prints last, and must be manually
  160.            inserted after the title page.
  161.  
  162.     2
  163.  
  164.  
  165.  
  166.  
  167.     _______ _   _________ ___ _____ __________
  168.     Chapter 2   Accessing the XPLIB Intrinsics
  169.  
  170.  
  171.                 _  ___ _____ _______
  172.                 ⁿ  The XPLIB Program
  173.                 _  ______ ____ ____
  174.                 ⁿ  Xpress User Name
  175.                 _  _______ ________
  176.                 ⁿ  Calling Sequence
  177.                 _  _____ ______ ____
  178.                 ⁿ  COBOL Sample File
  179.                 _  _________ ___ _______ __ ___ _
  180.                 ⁿ  Compiling and Linking on MPE V
  181.                 _  _________ ___ _______ __ ______
  182.                 ⁿ  Compiling and Linking on MPE/iX
  183.  
  184.  
  185.            The XPLIB intrinsics are a set of intrinsics that  can  be  called
  186.            from  compatibility- or native-mode programs.  You access XPLIB by
  187.            calling these intrinsics, just as you would  the  IMAGE  or  VPLUS
  188.            intrinsics.
  189.  
  190.  
  191.     ___ _____ _______
  192.     The XPLIB Program
  193.  
  194.            The  XPLIB  intrinsics  do  not  open  the  Xpress  Mail  database
  195.            directly.  All requests from the XPLIB intrinsics are processed by
  196.            the  XPLIB  program.   When you call the XPLIBINIT intrinsics, the
  197.            Xplib.Mail.Robelle program is created as a son process (unless you
  198.            have  overridden the filename).  An error is returned if the XPLIB
  199.            program cannot be run or if it cannot open the Mail database.
  200.  
  201.  
  202.     ______ ____ ____
  203.     Xpress User Name
  204.  
  205.            The XPLIB program works like every other Xpress program.   If  you
  206.            have  already  run  any  other  Xpress  program, the user name and
  207.            password from the last Xpress program will be used  by  the  XPLIB
  208.            program,  unless  you  explicitly  specify  the  user  name to the
  209.            XPLIBINIT intrinsic.  You can force the XPLIB  program  to  prompt
  210.            for the Xpress user name by setting the MailFileStatus JCW to zero
  211.            before running your program that calls the XPLIB intrinsics.
  212.  
  213.  
  214.     _______ ________
  215.     Calling Sequence
  216.  
  217.            These steps are required to use the XPLIB intrinsics:
  218.  
  219.            1. A workspace must be declared in your program.   This  workspace
  220.               must not change between calls to the various XPLIB intrinsics.
  221.  
  222.            2. The XPLIBINIT intrinsic must be called successfully.
  223.  
  224.            3. Other XPLIB intrinsics can be called as needed.
  225.  
  226.            4. When  the program is finished, it can tidy things up by calling
  227.               the XPLIBEND intrinsic.
  228.  
  229.                             _______ _   _________ ___ _____ __________
  230.                             Chapter 2   Accessing the XPLIB Intrinsics      3
  231.  
  232.  
  233.  
  234.     _____ ______ ____
  235.     COBOL Sample File
  236.  
  237.            The file Cobol3.Qlibsrc.Robelle contains  COBOL  declarations  for
  238.            all parameters required by the XPLIB intrinsics.  It also contains
  239.            template calls to each of the intrinsics.
  240.  
  241.  
  242.     _________ ___ _______ __ ___ _
  243.     Compiling and Linking on MPE V
  244.  
  245.            You require PH capability in order to use  the  XPLIB  intrinsics.
  246.            The   classic   object   code   for   the  intrinsics  resides  in
  247.            Xplibusl.Mail.Robelle.
  248.  
  249.            The intrinsics are installed in SL files.  The following  commands
  250.            demonstrate  how  to  compile  and prepare your program to use the
  251.            XPLIB intrinsics.  This example assumes that the  intrinsics  have
  252.            been installed in the system SL:
  253.  
  254.                 :cobol example.source
  255.                 :prep $oldpass,example.pub;cap=ph
  256.                 :save example.pub
  257.                 :run example.pub
  258.  
  259.  
  260.     _____ ____
  261.     Using Lib=
  262.  
  263.                 ______  __  ____________
  264.            The  System  SL  Installation  chapter  of the manual tells how to
  265.            install the  intrinsics  so  that  they  are  available  to  every
  266.            program.   In doing so, you will not have to run programs with the
  267.            Lib= parameter.
  268.  
  269.            You can also install the intrinsics in an SL  file  and  run  your
  270.            program  with  Lib=.   Here  is an example of how to add the XPLIB
  271.            segment from Xplibusl.Mail to your existing SL file.
  272.  
  273.                 :run fcopy.pub.sys
  274.                 >from=xplibusl.mail.robelle;to=xplibusl.pub;new
  275.                 >exit
  276.                 :segmenter
  277.                 -buildsl sl.pub,400,4    {fails if you already have an SL}
  278.                 -sl sl.pub
  279.                 -usl xplibusl.pub
  280.                 -addsl xplib
  281.                 -exit
  282.  
  283.            You can run your program (e.g., Callxp) with the Lib=P parameter:
  284.  
  285.                 :cobol callxp.source
  286.                 :prep $oldpass,callxp.program;cap=ph
  287.                 :save callxp.program
  288.  
  289.                 :run callxp.program;lib=p
  290.  
  291.            _______ _   _________ ___ _____ __________
  292.     4      Chapter 2   Accessing the XPLIB Intrinsics
  293.  
  294.  
  295.  
  296.     _____
  297.     Notes
  298.  
  299.            The MPE :Prep command prints a warning message  when  you  specify
  300.            cap=ph.   You  may  ignore this message or specify cap=ia,ba,ph on
  301.            your :Prep command.  If your program requires other  capabilities,
  302.            they should also be specified (e.g., cap=ph,ds).
  303.  
  304.            _______
  305.            Warning:    The  XPLIB  intrinsics  may  change  over  time.   The
  306.            intrinsics should never be installed directly into a program file.
  307.            They should only be installed into SL files.
  308.  
  309.  
  310.     _________ ___ _______ __ ______
  311.     Compiling and Linking on MPE/iX
  312.  
  313.            You  require  PH  capability in order to use the XPLIB intrinsics.
  314.            The intrinsics are installed in XL files.  The following  commands
  315.            demonstrate  how  to  compile  and  link  your  program to use the
  316.            XPLIB/iX intrinsics.
  317.  
  318.                 :cob74xl example.source
  319.                 :link from=$oldpass;to=example.pub;cap=ph
  320.                 :run example.pub;xl='xplibxl.mail.robelle'
  321.  
  322.  
  323.     ____ __ _____
  324.     User XL Files
  325.  
  326.            You can use MPE/iX's Linkedit command to add the XPLIB  intrinsics
  327.            to your own XL file.  For example,
  328.  
  329.                 :linkedit
  330.                 -xl xl.pub
  331.                 -copyxl from=xplibxl.mail.robelle
  332.                 -exit
  333.                 :run example.pub;xl='xl.pub'
  334.  
  335.                                                                             5
  336.  
  337.  
  338.  
  339.  
  340.     _______ _   _____ __________
  341.     Chapter 3   XPLIB Intrinsics
  342.  
  343.  
  344.                 _  ______ _____
  345.                 ⁿ  Status Array
  346.                 _  ___________
  347.                 ⁿ  Declaration
  348.                 _  __________ _________
  349.                 ⁿ  XPLIBCOUNT Intrinsic
  350.                 _  ________ _________
  351.                 ⁿ  XPLIBEND Intrinsic
  352.                 _  ____________ _________
  353.                 ⁿ  XPLIBEXPLAIN Intrinsic
  354.                 _  _________ _________
  355.                 ⁿ  XPLIBINIT Intrinsic
  356.                 _  _____________ _________
  357.                 ⁿ  XPLIBUSERFIND Intrinsic
  358.                 _  ____________ _________
  359.                 ⁿ  XPLIBUSERGET Intrinsic
  360.  
  361.  
  362.            In  this  chapter we describe the XPLIB intrinsics in alphabetical
  363.            order.  The parameters for each intrinsic are  word  arrays  (just
  364.            like  IMAGE intrinsic calls).  You must include every parameter or
  365.            pass a dummy variable as a place holder.  The  condition  code  is
  366.            not returned by any XPLIB intrinsic.
  367.  
  368.  
  369.     ______ _____
  370.     Status Array
  371.  
  372.            The  status  array  is a ten-word array.  You can use the standard
  373.            IMAGE status array or you can declare a  custom  status  parameter
  374.            for  the  XPLIB  intrinsics.   Where  it  makes  sense,  the XPLIB
  375.            intrinsics  return  error   numbers   similar   to   their   IMAGE
  376.            counterparts.    If   an   error   occurs,  you  should  call  the
  377.            XPLIBEXPLAIN intrinsic.
  378.  
  379.  
  380.     ___________
  381.     Declaration
  382.  
  383.            Here is a typical declaration for the status array:
  384.  
  385.                 01  xplib-status-area.
  386.                     05  xplib-cond-word        pic s9(4) comp.
  387.                         88  xplib-stat-ok          value zeros.
  388.                         88  xplib-end-of-users     value 15.
  389.                         88  xplib-no-entry         value 17.
  390.                     05  filler                 pic s9(4) comp
  391.                                                occurs 9 times.
  392.  
  393.            _______ _   _____ __________
  394.     6      Chapter 3   XPLIB Intrinsics
  395.  
  396.  
  397.  
  398.     __________ _________
  399.     XPLIBCOUNT Intrinsic
  400.  
  401.                                  __ ______  _____________     ________  _____
  402.            Returns the number of In Basket, Bring-Forward, or Bulletin  Board
  403.            messages  for  either  the user set up by the call to XPLIBINIT or
  404.            for a specific Xpress user.
  405.  
  406.                            __________ _____ _______ _________ ____
  407.                 XPLIBCOUNT Workspace, Mode, Status, Messages, User
  408.  
  409.  
  410.     _________
  411.     Workspace
  412.  
  413.            This  is  the  workspace  that  was  passed  to  XPLIBINIT.   This
  414.            workspace must not have changed since the call to XPLIBINIT.
  415.  
  416.  
  417.     ____
  418.     Mode
  419.  
  420.            There  is  one mode for each of the Xpress basket counts, a single
  421.            word integer from 1 to 3, or 11 to 13.  Modes 1 to  3  ignore  the
  422.            user  parameter  and use the user set up by the call to XPLIBINIT.
  423.            If you add ten to the mode (i.e., modes 11, 12, and 13), the  same
  424.            information  is  returned, but the count is for the user specified
  425.            in the user parameter.
  426.  
  427.                                                 __ ______
  428.            Modes 1 and 11. Return the number of In Basket messages.
  429.  
  430.                                                 _____________
  431.            Modes 2 and 12. Return the number of Bring-Forward messages.
  432.  
  433.                                                 ________ _____
  434.            Modes 3 and 13. Return the number of Bulletin Board messages  that
  435.                            the user has not read.
  436.  
  437.            For  modes  11,  12,  and  13,  the  user set by XPLIBINIT must be
  438.            Helpman.  This  avoids  any  potential  security  problems,  since
  439.            Helpman has access to all Xpress users.
  440.  
  441.  
  442.     ______
  443.     Status
  444.  
  445.            A  ten-word  array  of  16-bit  integers.  The return value of the
  446.            first word will be zero if the call to XPLIBCOUNT is successful.
  447.  
  448.  
  449.     ________
  450.     Messages
  451.  
  452.            The number of messages are returned to  this  variable,  a  16-bit
  453.            integer:
  454.  
  455.                  01  xplib-no-messages           pic s9(4) comp.
  456.  
  457.                                           _______ _   _____ __________
  458.                                           Chapter 3   XPLIB Intrinsics      7
  459.  
  460.  
  461.  
  462.     ____
  463.     User
  464.  
  465.            The  user  name  for  whom to return the number of messages.  This
  466.            parameter is only used for modes 11, 12, and 13.   The  user  name
  467.            must be declared as follows:
  468.  
  469.                  01  xplib-user-name             pic x(26).
  470.  
  471.  
  472.     _______
  473.     Example
  474.  
  475.                                               __ ______
  476.            This example returns the number of In Basket messages for the user
  477.            set up by the call to XPLIBINIT.
  478.  
  479.                 call "XPLIBCOUNT" using xplib-workspace
  480.                                         xplib-mode1
  481.                                         xplib-status-area
  482.                                         xplib-no-messages
  483.                                         xplib-dummy-arg.
  484.                 if not xplib-stat-ok then
  485.                     perform 98-xplib-error
  486.  
  487.                                               _____________
  488.            This example returns the number of Bring-Forward messages for  the
  489.            Xpress user "RON JONES".  The example assumes that Helpman was set
  490.            up as the XPLIB user in the call to XPLIBINIT.
  491.  
  492.                 move "ron jones" to xplib-user-name.
  493.                 call "XPLIBCOUNT" using xplib-workspace
  494.                                         xplib-mode12
  495.                                         xplib-status-area
  496.                                         xplib-no-messages
  497.                                         xplib-user-name.
  498.                 if not xplib-stat-ok then
  499.                     perform 98-xplib-error
  500.  
  501.  
  502.     _____
  503.     Notes
  504.  
  505.                                                          __ ______
  506.            Many applications may only need the number of In Basket  messages.
  507.            This  is  one reason why not all of the basket counts are returned
  508.            in a single call to XPLIBCOUNT.  The  other  reason  is  that  the
  509.            number  of  disc  accesses required varies according to each mode.
  510.            Here is the summary for each mode:
  511.  
  512.            Mode 1 or 11.   One disc access.
  513.  
  514.            Mode 2 or 12.   Two disc  accesses  plus  the  number  of  visible
  515.                            _____________
  516.                            Bring-Forward messages.
  517.  
  518.            Mode 3 or 13.   Two  disc  accesses  plus  the  number  of  unread
  519.                            ________ _____
  520.                            Bulletin Board messages.
  521.  
  522.            _______ _   _____ __________
  523.     8      Chapter 3   XPLIB Intrinsics
  524.  
  525.  
  526.  
  527.     ________ _________
  528.     XPLIBEND Intrinsic
  529.  
  530.            Shuts down the Xpress  intrinsic  library.   This  terminates  the
  531.            XPLIB program and reinitializes the workspace parameter.
  532.  
  533.                          __________ _____ _______ _____
  534.                 XPLIBEND Workspace, Mode, Status, Dummy
  535.  
  536.  
  537.     _________
  538.     Workspace
  539.  
  540.            This  is  the  workspace  that  was  passed  to  XPLIBINIT.   This
  541.            workspace must not have changed since the call to XPLIBINIT.
  542.  
  543.  
  544.     ____
  545.     Mode
  546.  
  547.            The mode, a 16-bit integer, must contain a value of one.
  548.  
  549.  
  550.     ______
  551.     Status
  552.  
  553.            A ten-word array of 16-bit integers.   The  return  value  of  the
  554.            first word will be zero if the call to XPLIBEND is successful.
  555.  
  556.  
  557.     _____
  558.     Dummy
  559.  
  560.            This is a dummy parameter and it may contain anything.
  561.  
  562.  
  563.     _______
  564.     Example
  565.  
  566.                 call "XPLIBEND" using xplib-workspace
  567.                                       xplib-mode1
  568.                                       xplib-status-area
  569.                                       xplib-dummy-arg.
  570.                 if not xplib-stat-ok then
  571.                     perform 98-xplib-error.
  572.  
  573.                                           _______ _   _____ __________
  574.                                           Chapter 3   XPLIB Intrinsics      9
  575.  
  576.  
  577.  
  578.     ____________ _________
  579.     XPLIBEXPLAIN Intrinsic
  580.  
  581.            Prints  a  three-line  message  on  $Stdlist  which  describes the
  582.            results of an XPLIB intrinsic call based  on  information  in  the
  583.            status array.
  584.  
  585.                              ______
  586.                 XPLIBEXPLAIN status
  587.  
  588.  
  589.     ______
  590.     Status
  591.  
  592.            The status is a ten-word array of 16-bit integers used to call any
  593.            XPLIB intrinsic.
  594.  
  595.            _______ _   _____ __________
  596.     10     Chapter 3   XPLIB Intrinsics
  597.  
  598.  
  599.  
  600.     _________ _________
  601.     XPLIBINIT Intrinsic
  602.  
  603.            Initializes the Xpress intrinsic library.  Depending on the  mode,
  604.            you   may   also  use  the  XPLIBINIT  intrinsic  to  specify  the
  605.            run-parameters for the XPLIB program and the Xpress user  name  to
  606.            use for subsequent calls to the XPLIB intrinsics.
  607.  
  608.                           __________ _____ _______ ________ _________ _____
  609.                 XPLIBINIT Workspace, Mode, Status, RunParm, UserParm, Dummy
  610.  
  611.  
  612.     _________
  613.     Workspace
  614.  
  615.            The  workspace  is  used  by  the XPLIB intrinsics to store global
  616.            information.  This workspace must  not  change  between  calls  to
  617.            XPLIBINIT  and  any  of  the  other  XPLIB  intrinsics.  The COBOL
  618.            declaration and initial values for the workspace are as follows:
  619.  
  620.                  01  xplib-workspace.
  621.                      05  xplib-version-no     pic s9(4) comp value 1.
  622.                      05  filler               pic x(10) value spaces.
  623.  
  624.  
  625.     ____
  626.     Mode
  627.  
  628.            This is a single word integer, and may have the value 1, 2, 3,  or
  629.            5.
  630.  
  631.  
  632.     ______
  633.     Mode-1
  634.  
  635.            Initialize  the  Xpress intrinsic library.  Use Xplib.Mail.Robelle
  636.            for processing.  If no Xpress program has been run, XPLIBINIT will
  637.            prompt  for the Xpress user name and user password.  You must pass
  638.            a dummy parameter for the run-parameter and the user-parameter.
  639.  
  640.                 call "XPLIBINIT" using xplib-workspace
  641.                                        xplib-mode1
  642.                                        xplib-status-area
  643.                                        xplib-dummy-arg
  644.                                        xplib-dummy-arg
  645.                                        xplib-dummy-arg.
  646.                 if not xplib-stat-ok then
  647.                     perform 98-xplib-error.
  648.  
  649.  
  650.     ______
  651.     Mode-2
  652.  
  653.            Initialize the library, but specify the  name  and  run-parameters
  654.            for  the  XPLIB  program.   With  Mode-2,  you  must pass a fourth
  655.            parameter  to  XPLIBINIT  (see  below  for  how  to  declare   the
  656.            run-parameters).  Pass a dummy parameter for the user-parameter.
  657.  
  658.                                           _______ _   _____ __________
  659.                                           Chapter 3   XPLIB Intrinsics     11
  660.  
  661.  
  662.  
  663.                 call "XPLIBINIT" using xplib-workspace
  664.                                        xplib-mode2
  665.                                        xplib-status-area
  666.                                        xplib-run-parm
  667.                                        xplib-dummy-arg
  668.                                        xplib-dummy-arg.
  669.                 if not xplib-stat-ok then
  670.                     perform 98-xplib-error.
  671.  
  672.  
  673.     ______
  674.     Mode-3
  675.  
  676.            You  can specify which Xpress user the XPLIB intrinsics should use
  677.            with Mode-3.  With Mode-3, you must  pass  a  fifth  parameter  to
  678.            XPLIBINIT  (see  below  for  the user-parameter declaration).  You
  679.            must pass a dummy parameter for the run-parameter.
  680.  
  681.                 call "XPLIBINIT" using xplib-workspace
  682.                                        xplib-mode3
  683.                                        xplib-status-area
  684.                                        xplib-dummy-arg
  685.                                        xplib-user-parm
  686.                                        xplib-dummy-arg.
  687.                 if not xplib-stat-ok then
  688.                     perform 98-xplib-error.
  689.  
  690.  
  691.     ______
  692.     Mode-5
  693.  
  694.            With Mode-5, you can specify the XPLIB program run-parameters, and
  695.            the  Xpress user name to use with the XPLIB library.  Effectively,
  696.            this combines Mode-2 and Mode-3.  For Mode-5, you must  pass  both
  697.            the XPLIB run-parameter and user-parameter:
  698.  
  699.                 call "XPLIBINIT" using xplib-workspace
  700.                                        xplib-mode5
  701.                                        xplib-status-area
  702.                                        xplib-run-parm
  703.                                        xplib-user-parm
  704.                                        xplib-dummy-arg.
  705.                 if not xplib-stat-ok then
  706.                     perform 98-xplib-error.
  707.  
  708.  
  709.     ______
  710.     Status
  711.  
  712.            A  ten-word  array  of  16-bit  integers.  The return value of the
  713.            first word will be zero if the call to  XPLIBINIT  is  successful.
  714.            Twenty  will  be  returned if no Xpress user is active, and you do
  715.            not specify an Xpress user to XPLIBINIT, and no Xpress  user  name
  716.            is specified to the XPLIB program.
  717.  
  718.            _______ _   _____ __________
  719.     12     Chapter 3   XPLIB Intrinsics
  720.  
  721.  
  722.  
  723.     ___ _________
  724.     Run Parameter
  725.  
  726.            When  using Mode-2 or Mode-5, you must pass a parameter describing
  727.            how you want to run the XPLIB program.  It has the following COBOL
  728.            declaration:
  729.  
  730.                  01  xplib-run-parms.
  731.                      05  xplib-run-version     pic s9(4) comp value 1.
  732.                      05  xplib-run-progname    pic x(36)
  733.                          value "xplib.mail.dev".
  734.                      05  xplib-run-lib         pic s9(4) comp value 0.
  735.                      05  xplib-run-parm        pic s9(4) comp value 2.
  736.  
  737.           _________________
  738.           xplib-run-version must have the value one.
  739.  
  740.           __________________
  741.           xplib-run-progname is the name of the actual XPLIB program.  In our
  742.                  example, it is Xplib.Mail.Dev.
  743.  
  744.           _____________
  745.           xplib-run-lib is the library search to use when running  the  XPLIB
  746.                  program.  The valid values are as follows:
  747.                      0. Lib=S
  748.                      1. Lib=P
  749.                      2. Lib=G
  750.  
  751.           ______________
  752.           xplib-run-parm  is  the  Parm=  value to use when running the XPLIB
  753.                  program.  If you have moved the Xpress  Mail  database,  you
  754.                                            ______________
  755.                  will  need  to  set  the  xplib-run-parm to 2.  If your Mail
  756.                  database is in the Maildb group of the Robelle account,  you
  757.                             ______________
  758.                  should set xplib-run-parm to zero.
  759.  
  760.  
  761.     ____ _________
  762.     User Parameter
  763.  
  764.            When  using Mode-3 or Mode-5, you must pass a parameter describing
  765.            the Xpress user name and user password.  This  parameter  has  the
  766.            following COBOL declaration:
  767.  
  768.                  01  xplib-user-parms.
  769.                      05  xplib-user-version    pic s9(4) comp value 1.
  770.                      05  xplib-user-name       pic x(26) value spaces.
  771.                      05  xplib-user-password   pic x(20) value spaces.
  772.  
  773.           __________________
  774.           xplib-user-version must have the value one.
  775.  
  776.           _______________
  777.           xplib-user-name is the name of the Xpress user to use when invoking
  778.                  the XPLIB program.   If  the  name  is  invalid,  the  XPLIB
  779.                  program will prompt for a valid name.
  780.  
  781.           ___________________
  782.           xplib-user-password  is  the  Xpress  user  password  to  use  when
  783.                  invoking the XPLIB program.  If the password is invalid, the
  784.                  XPLIB program will prompt for a valid one.
  785.  
  786.                                           _______ _   _____ __________
  787.                                           Chapter 3   XPLIB Intrinsics     13
  788.  
  789.  
  790.  
  791.     _____
  792.     Dummy
  793.  
  794.            This is a dummy parameter and it may contain anything.
  795.  
  796.  
  797.     _____
  798.     Notes
  799.  
  800.            The  XPLIBINIT  intrinsic  creates  the  XPLIB  program  as  a son
  801.            process.  The XPLIB program must open the  Xpress  Mail  database,
  802.            open  other  files,  obtain  the  user  name,  and  execute  other
  803.            initializations.  This  involves  a  lot  of  overhead.   We  have
  804.            designed   the  XPLIB  intrinsics  assuming  that  you  will  call
  805.            XPLIBINIT once at the start of your program.  You cannot call  any
  806.            other  XPLIB  intrinsic  until  you  have  successfully called the
  807.            XPLIBINIT intrinsic.
  808.  
  809.            _______ _   _____ __________
  810.     14     Chapter 3   XPLIB Intrinsics
  811.  
  812.  
  813.  
  814.     _____________ _________
  815.     XPLIBUSERFIND Intrinsic
  816.  
  817.            Checks the Mail database to see if a user name exists or not.
  818.  
  819.                               __________ _____ _______ ____
  820.                 XPLIBUSERFIND Workspace, Mode, Status, User
  821.  
  822.  
  823.     _________
  824.     Workspace
  825.  
  826.            This  is  the  workspace  that  was  passed  to  XPLIBINIT.   This
  827.            workspace must not have changed since the call to XPLIBINIT.
  828.  
  829.  
  830.     ____
  831.     Mode
  832.  
  833.            There  are  two  modes  for  calling  XPLIBUSERFIND, one for exact
  834.            matches and one for partial matches:
  835.  
  836.            1. See if the passed user name exists.  The user name must  be  an
  837.               exact match to an existing Xpress user name.
  838.  
  839.            2. Find  all users that match the passed user name.  The number of
  840.               matching users is returned in the status array.
  841.  
  842.  
  843.     ______
  844.     Status
  845.  
  846.            A ten-word array of 16-bit integers.   The  return  value  of  the
  847.            first  word  will be zero if the user name passed to XPLIBUSERFIND
  848.            exists.  If the user name does not exist, seventeen is returned in
  849.            the  condition word.  If XPLIBUSERFIND was called with Mode-2, the
  850.            number of matching user names is returned in status-words five and
  851.            six  (these  are  the  same words to which IMAGE returns the chain
  852.            length after a call to DBFIND).
  853.  
  854.  
  855.     ____
  856.     User
  857.  
  858.            This is the Xpress user name that you are looking for.  This  must
  859.            be  a  twenty-six  character  buffer padded with spaces.  The user
  860.            name can be in lower case, upper case, or mixed case.  For Mode-1,
  861.            the  user  name must be spelled in full, just as you would type it
  862.            into Xpress.  For Mode-2, it can be any leading characters  in  an
  863.            Xpress user name and must not be blank.
  864.  
  865.                  01  user-name                   pic x(26)
  866.                      value "joe smith".
  867.  
  868.                                           _______ _   _____ __________
  869.                                           Chapter 3   XPLIB Intrinsics     15
  870.  
  871.  
  872.  
  873.     _______
  874.     Example
  875.  
  876.                 call "XPLIBUSERFIND" using xplib-workspace
  877.                                            xplib-mode1
  878.                                            xplib-status-area
  879.                                            user-name.
  880.                 if not xplib-stat-ok then
  881.                     perform 98-xplib-error.
  882.  
  883.            _______ _   _____ __________
  884.     16     Chapter 3   XPLIB Intrinsics
  885.  
  886.  
  887.  
  888.     ____________ _________
  889.     XPLIBUSERGET Intrinsic
  890.  
  891.            XPLIBUSERGET  returns all Xpress user names that matched a partial
  892.            user name from a call to XPLIBUSERFIND.
  893.  
  894.                              __________ _____ _______ ____
  895.                 XPLIBUSERGET Workspace, Mode, Status, User
  896.  
  897.  
  898.     _________
  899.     Workspace
  900.  
  901.            This  is  the  workspace  that  was  passed  to  XPLIBINIT.   This
  902.            workspace must not have changed since the call to XPLIBINIT.
  903.  
  904.  
  905.     ____
  906.     Mode
  907.  
  908.            The mode must be one.
  909.  
  910.  
  911.     ______
  912.     Status
  913.  
  914.            A  ten-word  array  of  16-bit  integers.  The return value of the
  915.            first word will be zero  while  there  are  still  user  names  to
  916.            return.   After  the  last  user name has been returned, the first
  917.            word  is  set  to  fifteen  (the  same  value   IMAGE   uses   for
  918.            end-of-chain).
  919.  
  920.  
  921.     ____
  922.     User
  923.  
  924.            The  next  Xpress  user name.  This must be a twenty-six character
  925.            buffer.  XPLIBUSERGET always pads the user name with spaces.
  926.  
  927.                 01  user-name                   pic x(26).
  928.  
  929.  
  930.     _______
  931.     Example
  932.  
  933.                 call "XPLIBUSERGET" using xplib-workspace
  934.                                           xplib-mode1
  935.                                           xplib-status-area
  936.                                           user-name.
  937.                 if not xplib-stat-ok and not xplib-end-of-users then
  938.                     perform 98-xplib-error.
  939.  
  940.                                                                            17
  941.  
  942.  
  943.  
  944.  
  945.     _______ _   _____ _____ ________
  946.     Chapter 4   XPLIB Error Messages
  947.  
  948.  
  949.            XPLIB returns error numbers in the status parameter.   Each  error
  950.            is  associated  with  an  error  number.   Positive  error numbers
  951.            indicate  warnings  and  negative  error  numbers  indicate  fatal
  952.            problems.   The following are the error numbers, descriptions, and
  953.            causes that can be returned by any XPLIB intrinsic.
  954.  
  955.  
  956.     ____  _______ ____
  957.     -20:  Invalid mode
  958.  
  959.            The mode passed to an XPLIB intrinsic is not  valid.   Check  that
  960.            the mode is being passed as the second parameter and ensure that a
  961.            valid value is being specified.
  962.  
  963.  
  964.     ____  _______ _______ ______ _
  965.     -21:  Invalid version number n
  966.  
  967.            The version number in the workspace parameter does  not  have  the
  968.            value  one.  Ensure that the workspace is declared correctly.  The
  969.            first field in the workspace must be a  16-bit  integer  with  the
  970.            value one.
  971.  
  972.  
  973.     ____  _____________ _____
  974.     -22:  Createprocess error
  975.  
  976.            A call to the createprocess intrinsic has failed.  This message is
  977.            followed by an additional line showing  the  actual  createprocess
  978.            error  message.   When calling XPLIBINIT with Mode-2 or Mode-5, be
  979.                          __________________
  980.            sure that the xplib-run-progname field is  correct.   The  reasons
  981.            that this error may occur are as follows:
  982.  
  983.            ⁿ  The program Xplib.Mail.Robelle does not exist.
  984.  
  985.                                                      __________________
  986.            ⁿ  The  program filename specified in the xplib-run-progname field
  987.               is not spelled correctly.
  988.  
  989.            ⁿ  You forgot to :Prep or :Link your program with cap=ph.
  990.  
  991.            ⁿ  Your machine is out of resources to run more processes.
  992.  
  993.  
  994.     ____  _______ _______ ______ ___ ___ __________ _
  995.     -23:  Invalid version number for run parameters n
  996.  
  997.                                                ___ __________
  998.            The version number specified in the run parameters does  not  have
  999.            the value one.  The version number passed to XPLIBINIT is printed.
  1000.            Ensure that the version number of the run-parameter is  the  first
  1001.            field  and  that it is declared as a 16-bit integer with the value
  1002.            one.
  1003.  
  1004.            _______ _   _____ _____ ________
  1005.     18     Chapter 4   XPLIB Error Messages
  1006.  
  1007.  
  1008.  
  1009.     ____  _______ ___ _______ _
  1010.     -24:  Invalid run library n
  1011.  
  1012.            The library field of the run-parameters does not have the value 0,
  1013.            1, or 2.  The actual value passed to XPLIBINIT is printed.  Ensure
  1014.            that the run-parameter library field is a 16-bit  integer  with  a
  1015.            valid value.
  1016.  
  1017.  
  1018.     ____  __ ______ ___ _______ ___ _______ ____
  1019.     -25:  No active son process for sending mail
  1020.  
  1021.            This  error  should  never occur.  If it does, please report it to
  1022.            Robelle Consulting Ltd.
  1023.  
  1024.  
  1025.     ____  ______ __ ________ ___ _______
  1026.     -26:  Unable to activate son process
  1027.  
  1028.            This error should never occur.  If it does, please  report  it  to
  1029.            Robelle Solutions Technology Inc.
  1030.  
  1031.  
  1032.     ____  _____ _______ __________
  1033.     -27:  Xplib program terminated
  1034.  
  1035.            This  error  occurs  whenever  the XPLIB program terminates.  When
  1036.            calling XPLIBINIT, the most common reason for this error  is  that
  1037.            XPLIB  could not open the Password file or the Mail database.  For
  1038.            the other intrinsics, this error usually indicates that the  XPLIB
  1039.            program failed with a fatal error.
  1040.  
  1041.  
  1042.     ____  ________ ______ __ ________ _______ _
  1043.     -28:  Sendmail failed -- sendmail status: n
  1044.  
  1045.            This  error  should  never occur.  If it does, please report it to
  1046.            Robelle Solutions Technology Inc.
  1047.  
  1048.  
  1049.     ____  ___________ ______ __ ___________ _______ _
  1050.     -29:  Receivemail failed -- receivemail status: n
  1051.  
  1052.            This error should never occur.  If it does, please  report  it  to
  1053.            Robelle Solutions Technology Inc.
  1054.  
  1055.  
  1056.     ____  _______ ________ ___________ _____ _
  1057.     -30:  Invalid internal transaction type: n
  1058.  
  1059.            This  error  should  never occur.  If it does, please report it to
  1060.            Robelle Solutions Technology Inc.
  1061.  
  1062.  
  1063.     ____  ______ __ ____ _____ ___ _______
  1064.     -31:  Unable to kill Xplib son process
  1065.  
  1066.            This error should never occur.  If it does, please  report  it  to
  1067.            Robelle Solutions Technology Inc.
  1068.  
  1069.                                       _______ _   _____ _____ ________
  1070.                                       Chapter 4   XPLIB Error Messages     19
  1071.  
  1072.  
  1073.  
  1074.     ____  _______ _______ ______ ___ ____ __________ _
  1075.     -32:  Invalid version number for user parameters n
  1076.  
  1077.                                                 ____ __________
  1078.            The  version number specified in the user parameters does not have
  1079.            the value one.  The version number passed to XPLIBINIT is printed.
  1080.            Ensure  that  the user-parameter version number is the first field
  1081.            and that it is declared as a 16-bit integer with the value one.
  1082.  
  1083.  
  1084.     ____  ____ __ ______ _______  ______ _ _
  1085.     -33:  Call to PUTJCW failed.  Status = n
  1086.  
  1087.            This error should never occur.  If it does, please  report  it  to
  1088.            Robelle Solutions Technology Inc.
  1089.  
  1090.  
  1091.     ____  _________ _________ ___ ____ ________
  1092.     -34:  Workspace parameter has been modified
  1093.  
  1094.            Between  calls  to  the  XPLIB intrinsics, the XPLIB workspace has
  1095.            been changed.  Ensure that the workspace has not been  overwritten
  1096.            by  calls  to  other  subroutines.   You must also ensure that the
  1097.            workspace is a global data structure.
  1098.  
  1099.  
  1100.     ____  _______ ____ __ ___ ____ ___ _____ ___ ___ ___ __
  1101.     -35:  Helpman must be the user for modes 11, 12, and 13
  1102.  
  1103.            When calling XPLIBCOUNT  with  modes  11,  12,  or  13,  the  user
  1104.            specified for the XPLIB program (either explicitly in XPLIBINIT or
  1105.            when the XPLIB program prompts for the Xpress user name)  must  be
  1106.            Helpman.
  1107.  
  1108.  
  1109.     ___  ___ __ ____ _____
  1110.     15:  End of user names
  1111.  
  1112.            Returned when XPLIBUSERGET has no more user names to return.
  1113.  
  1114.  
  1115.     ___  __ _____ _____
  1116.     17:  No entry found
  1117.  
  1118.            Returned   when   XPLIBCOUNT  or  XPLIBUSERFIND  cannot  find  the
  1119.            requested Xpress user name.  For Mode-2  calls  to  XPLIBUSERFIND,
  1120.            there  was  no  Xpress  user  that  matched  the  name  passed  to
  1121.            XPLIBUSERFIND.
  1122.  
  1123.  
  1124.     ___  __ ____ _________ ___ ___ _____ _______
  1125.     20:  No user specified for the XPLIB program
  1126.  
  1127.            No valid user name was specified to the XPLIB program.  This error
  1128.            is returned by XPLIBINIT when the XPLIB program prompts for a user
  1129.            name and none is entered.
  1130.  
  1131.     20
  1132.  
  1133.  
  1134.  
  1135.  
  1136.     _______ _   _____ _______
  1137.     Chapter 5   COBOL Example
  1138.  
  1139.  
  1140.                                                                  __   ______
  1141.            The  following  program  displays  the  number   of   In   Basket,
  1142.            _____________        ________  _____
  1143.            Bring-Forward,  and  Bulletin  Board  messages for an Xpress user.
  1144.            This example also shows how to specify a non-standard name for the
  1145.            XPLIB  program.   An  Info= string will be used as the Xpress user
  1146.            name.  If no Info= string is specified, we either  use  an  Xpress
  1147.            user name that was entered previously or the XPLIB program prompts
  1148.            for a user name.
  1149.  
  1150.            $control nolist
  1151.            $control source,errors=10
  1152.             identification division.
  1153.             program-id.    testcob.
  1154.             author.        David Greer, Robelle Solutions Technology Inc.
  1155.             date-written.  Jan 2, 1991.
  1156.             security.       Copyright  Robelle  Solutions   Technology   Inc.
  1157.            1991-2007.
  1158.             remarks.
  1159.  
  1160.            ************************************************************
  1161.            *                                                          *
  1162.            *                testcob - test xplib intrinsics.          *
  1163.            *                                                          *
  1164.            *  version:  1.0                                           *
  1165.            *  purpose:                                                *
  1166.            *                                                          *
  1167.            *  General-purpose program to test the XPLIB intrinsics.   *
  1168.            *                                                          *
  1169.            *  Demonstrates that you can call all XPLIB routines from  *
  1170.            *  COBOL in CM and NM.                                     *
  1171.            *                                                          *
  1172.            ************************************************************
  1173.  
  1174.             environment division.
  1175.             configuration section.
  1176.             special-names.
  1177.                 top is new-page.
  1178.  
  1179.            $page "constants"
  1180.             data division.
  1181.             working-storage section.
  1182.             01  true-value                  pic x value "T".
  1183.             01  false-value                 pic x value "F".
  1184.  
  1185.            $page "variables"
  1186.             01  input-line                  pic x(80).
  1187.                 88  answer-spaces           value spaces.
  1188.  
  1189.             01  jcw-name                    pic x(255).
  1190.  
  1191.             01  jcw-status                  pic s9(4) comp.
  1192.  
  1193.                                              _______ _   _____ _______
  1194.                                              Chapter 5   COBOL Example     21
  1195.  
  1196.  
  1197.  
  1198.             01  info-string                 pic x(80) value spaces.
  1199.  
  1200.             01  info-length                 pic s9(4) comp value 80.
  1201.  
  1202.             01  info-result                 pic s9(4) comp.
  1203.  
  1204.             01  parm-value                  pic s9(4) comp.
  1205.            $page "xplib- variables"
  1206.  
  1207.             01  xplib-mode                  pic s9(4) comp.
  1208.  
  1209.             01  xplib-mode1                 pic s9(4) comp value 1.
  1210.  
  1211.             01  xplib-dummy-arg             pic s9(4) comp.
  1212.  
  1213.             01  xplib-status-area.
  1214.                 05  xplib-cond-word        pic s9(4) comp.
  1215.                     88  xplib-stat-ok          value zeros.
  1216.                     88  xplib-end-of-users     value 15.
  1217.                     88  xplib-no-entry         value 17.
  1218.                 05  filler                 pic s9(4) comp
  1219.                                            occurs 3 times.
  1220.                 05  xplib-user-count       pic s9(9) comp.
  1221.                 05  filler                 pic s9(4) comp
  1222.                                            occurs 4 times.
  1223.             01  xplib-workspace.
  1224.                 05  xplib-version-no        pic s9(4) comp value 1.
  1225.                 05  filler                  pic x(10) value spaces.
  1226.  
  1227.             01  xplib-run-parms.
  1228.                 05  xplib-run-version       pic s9(4) comp value 1.
  1229.                 05  xplib-run-progname      pic x(36)
  1230.                     value "xplib.mail.robelle".
  1231.                 05  xplib-run-lib           pic s9(4) comp value 0.
  1232.                 05  xplib-run-parm          pic s9(4) comp value 3.
  1233.  
  1234.             01  xplib-user-parms.
  1235.                 05  xplib-user-version      pic s9(4) comp value 1.
  1236.                 05  xplib-user-name         pic x(26) value spaces.
  1237.                 05  xplib-user-password     pic x(20) value spaces.
  1238.  
  1239.             01  xplib-no-messages           pic s9(4) comp.
  1240.  
  1241.             01  display-no-messages         pic z9.
  1242.            $page "[00] mainline"
  1243.             procedure division.
  1244.             00-main                         section.
  1245.  
  1246.                 perform 00-05-get-user-name.
  1247.  
  1248.                 perform 00-10-init-xplib.
  1249.  
  1250.                 perform 00-20-count-messages
  1251.                 varying xplib-mode from 1 by 1
  1252.  
  1253.            _______ _   _____ _______
  1254.     22     Chapter 5   COBOL Example
  1255.  
  1256.  
  1257.  
  1258.                   until xplib-mode > 3.
  1259.  
  1260.                 perform 00-90-end-xplib.
  1261.  
  1262.                 go to 00-main-exit.
  1263.  
  1264.             00-05-get-user-name.
  1265.                 call intrinsic "GETINFO" using info-string
  1266.                                                info-length
  1267.                                                parm-value
  1268.                      giving info-result.
  1269.                  if info-length > 0 and info-result = 0 then
  1270.                      move info-string      to xplib-user-name
  1271.                      move "MAILPASS"       to xplib-user-password
  1272.                      move 5                to xplib-mode
  1273.                  else
  1274.                      move 2                to xplib-mode.
  1275.  
  1276.             00-10-init-xplib.
  1277.                 call "XPLIBINIT" using xplib-workspace
  1278.                                        xplib-mode
  1279.                                        xplib-status-area
  1280.                                        xplib-run-parms
  1281.                                        xplib-user-parms
  1282.                                        xplib-dummy-arg.
  1283.                 if not xplib-stat-ok then
  1284.                     perform 98-xplib-error.
  1285.  
  1286.             00-20-count-messages.
  1287.                 call "XPLIBCOUNT" using xplib-workspace
  1288.                                         xplib-mode
  1289.                                         xplib-status-area
  1290.                                         xplib-no-messages
  1291.                                         xplib-dummy-arg.
  1292.                 if not xplib-stat-ok then
  1293.                     perform 98-xplib-error
  1294.                 else
  1295.                     perform 00-30-display-count
  1296.                     perform 00-40-update-jcw.
  1297.  
  1298.             00-30-display-count.
  1299.                 move xplib-no-messages to display-no-messages.
  1300.                 if xplib-mode = 1 then
  1301.                     display "In Basket:      ", display-no-messages
  1302.                 else
  1303.                 if xplib-mode = 2 then
  1304.                     display "Bring-Forward:  ", display-no-messages
  1305.                 else
  1306.                 if xplib-mode = 3 then
  1307.                     display "Bulletin Board: ", display-no-messages.
  1308.  
  1309.             00-40-update-jcw.
  1310.                 if xplib-mode = 1 then
  1311.                     move  "INBASKET      " to jcw-name
  1312.  
  1313.                                              _______ _   _____ _______
  1314.                                              Chapter 5   COBOL Example     23
  1315.  
  1316.  
  1317.  
  1318.                 else
  1319.                 if xplib-mode = 2 then
  1320.                     move  "BRINGFORWARD  " to jcw-name
  1321.                 else
  1322.                 if xplib-mode = 3 then
  1323.                     move  "BULLETINBOARD " to jcw-name.
  1324.                 call intrinsic "PUTJCW" using jcw-name
  1325.                                               xplib-no-messages
  1326.                                               jcw-status.
  1327.                 if jcw-status <> 0 then
  1328.                    display "Putjcw failed.  Status = ", jcw-status
  1329.                    call intrinsic "QUIT" using jcw-status.
  1330.  
  1331.             00-90-end-xplib.
  1332.                 call "XPLIBEND" using xplib-workspace
  1333.                                       xplib-mode1
  1334.                                       xplib-status-area
  1335.                                       xplib-dummy-arg.
  1336.                 if not xplib-stat-ok then
  1337.                     perform 98-xplib-error.
  1338.  
  1339.             00-main-exit.  goback.
  1340.            $page "[98] xplib-error"
  1341.  
  1342.             98-xplib-error                   section.
  1343.  
  1344.                 call "XPLIBEXPLAIN" using xplib-status-area.
  1345.  
  1346.                 call intrinsic "QUIT" using xplib-cond-word.
  1347.  
  1348.             98-xplib-error-exit.  goback.
  1349.  
  1350.     24
  1351.  
  1352.  
  1353.  
  1354.  
  1355.     _______ _   ______ _______
  1356.     Chapter 6   Pascal Example
  1357.  
  1358.  
  1359.            The  following Pascal program works exactly like our example COBOL
  1360.            program.  This example program compiles and  runs  in  native-mode
  1361.                                                                  ________
  1362.            under MPE/iX, but you must delete the declaration for shortint.
  1363.  
  1364.            $list off$
  1365.            program driver(input,output);
  1366.            type
  1367.               longint  = integer;
  1368.               shortint = -32768 ..  +32767;  {Remove for MPE/iX}
  1369.  
  1370.               type_workspace =
  1371.               record
  1372.                  version_no        : shortint;
  1373.                  filler            : array[1..5] of shortint;
  1374.               end;
  1375.  
  1376.               type_status_area = array[1..10] of shortint;
  1377.  
  1378.               type_mode = shortint;
  1379.  
  1380.               type_run_parm =
  1381.               record
  1382.                   version_no        : shortint;
  1383.                   progname          : packed array [1..36] of char;
  1384.                   run_lib           : shortint;
  1385.                   run_parm          : shortint;
  1386.               end;
  1387.  
  1388.               type_user_parm =
  1389.               record
  1390.                  version_no        : shortint;
  1391.                  user_name         : packed array [1..26] of char;
  1392.                  user_password     : packed array [1..20] of char;
  1393.               end;
  1394.  
  1395.               type_dummy_arg = array[1..2] of shortint;
  1396.  
  1397.            $check_formal_parm 2$
  1398.            $check_actual_parm 2$
  1399.  
  1400.               procedure xplibinit(var xplib_workspace  : type_workspace;
  1401.                                   var xplib_mode       : type_mode;
  1402.                                   var xplib_status_area: type_status_area;
  1403.                                   var xplib_run_parm   : type_run_parm;
  1404.                                   var xplib_user_parm  : type_user_parm;
  1405.                                   var xplib_dummy_arg  : type_dummy_arg
  1406.                                  ); external spl;
  1407.  
  1408.               procedure xplibcount(var xplib_workspace  : type_workspace;
  1409.                                    var xplib_mode       : type_mode;
  1410.  
  1411.                                             _______ _   ______ _______
  1412.                                             Chapter 6   Pascal Example     25
  1413.  
  1414.  
  1415.  
  1416.                                    var xplib_status_area: type_status_area;
  1417.                                    var xplib_no_messages: shortint;
  1418.                                    var xplib_dummy_arg  : type_dummy_arg
  1419.                                   ); external spl;
  1420.  
  1421.               procedure xplibend(var xplib_workspace : type_workspace;
  1422.                                  var xplib_mode       : type_mode;
  1423.                                  var xplib_status_area: type_status_area;
  1424.                                  var xplib_dummy_arg  : type_dummy_arg
  1425.                                 ); external spl;
  1426.  
  1427.               procedure xplibexplain
  1428.                            (var xplib_status_area : type_status_area
  1429.                            ); external spl;
  1430.  
  1431.               procedure quit; intrinsic;
  1432.               procedure putjcw; intrinsic;
  1433.               procedure getinfo; intrinsic;
  1434.  
  1435.            $check_formal_parm 3$
  1436.  
  1437.            procedure test_xplib;
  1438.            var
  1439.               xplib_workspace   : type_workspace;
  1440.               xplib_run_parm    : type_run_parm;
  1441.               xplib_status_area : type_status_area;
  1442.               xplib_user        : type_user_parm;
  1443.  
  1444.               procedure fatal_xplib_error;
  1445.               begin
  1446.                  xplibexplain(xplib_status_area);
  1447.                  quit(xplib_status_area[1]);
  1448.               end;   {fatal_xplib_error}
  1449.  
  1450.               procedure init_xplib(xplib_mode: type_mode);
  1451.               var
  1452.                  dummy_arg_user : type_user_parm;
  1453.                  dummy_arg      : type_dummy_arg;
  1454.               begin
  1455.                  xplib_workspace.version_no := 1;
  1456.                  xplib_run_parm.version_no  := 1;
  1457.                  xplib_run_parm.progname    := 'xplib.mail.robelle';
  1458.                  xplib_run_parm.run_lib     := 0;
  1459.                  xplib_run_parm.run_parm    := 2;
  1460.                  xplibinit(xplib_workspace
  1461.                           ,xplib_mode
  1462.                           ,xplib_status_area
  1463.                           ,xplib_run_parm
  1464.                           ,xplib_user
  1465.                           ,dummy_arg
  1466.                           );
  1467.                  if xplib_status_area[1] <> 0 then
  1468.                     fatal_xplib_error;
  1469.               end;   {init_xplib}
  1470.  
  1471.            _______ _   ______ _______
  1472.     26     Chapter 6   Pascal Example
  1473.  
  1474.  
  1475.  
  1476.               procedure print_count(xplib_mode: type_mode;
  1477.                                     count     : shortint
  1478.                                    );
  1479.               begin
  1480.                  case xplib_mode of
  1481.                  1 : write('In Basket     ');
  1482.                  2 : write('Bring Forward ');
  1483.                  3 : write('Bulletin Board');
  1484.                  end;
  1485.                  writeln(' = ',count:1);
  1486.               end;  {print_count}
  1487.  
  1488.               procedure update_jcw(xplib_mode: type_mode; count : shortint);
  1489.               var
  1490.                  jcwname : packed array[1..255] of char;
  1491.                  jcw_status : shortint;
  1492.               begin
  1493.                  case xplib_mode of
  1494.                  1 : jcwname := 'INBASKET';
  1495.                  2 : jcwname := 'BRINGFORWARD';
  1496.                  3 : jcwname := 'BULLETINBOARD';
  1497.                  end;
  1498.                  putjcw(jcwname,count,jcw_status);
  1499.                  if jcw_status <> 0 then
  1500.                  begin
  1501.                     writeln('PUTJCW failed with status = ',jcw_status:1);
  1502.                     quit(jcw_status);
  1503.                  end;
  1504.               end;  {update_jcw}
  1505.  
  1506.               procedure count_xplib(xplib_mode : shortint);
  1507.               var
  1508.                  xplib_messages : shortint;
  1509.                  dummy_arg     : type_dummy_arg;
  1510.               begin
  1511.                  xplibcount(xplib_workspace
  1512.                            ,xplib_mode
  1513.                            ,xplib_status_area
  1514.                            ,xplib_messages
  1515.                            ,dummy_arg
  1516.                            );
  1517.                  if xplib_status_area[1] <> 0 then
  1518.                     fatal_xplib_error;
  1519.                  print_count(xplib_mode,xplib_messages);
  1520.                  update_jcw(xplib_mode,xplib_messages);
  1521.               end;   {count_xplib}
  1522.  
  1523.               procedure end_xplib;
  1524.               var
  1525.                  xplib_mode : type_mode;
  1526.                  dummy_arg  : type_dummy_arg;
  1527.               begin
  1528.                  xplib_mode := 1;
  1529.                  xplibend(xplib_workspace
  1530.  
  1531.                                             _______ _   ______ _______
  1532.                                             Chapter 6   Pascal Example     27
  1533.  
  1534.  
  1535.  
  1536.                          ,xplib_mode
  1537.                          ,xplib_status_area
  1538.                          ,dummy_arg
  1539.                          );
  1540.                  if xplib_status_area[1] <> 0 then
  1541.                     fatal_xplib_error;
  1542.               end;  {end_xplib}
  1543.  
  1544.               function get_user_name : boolean;
  1545.               var
  1546.                  info_buf    : packed array [1..26] of char;
  1547.                  info_len    : shortint;
  1548.                  info_parm   : shortint;
  1549.               begin {get_user_name}
  1550.                  info_len := 26;
  1551.                  info_buf := ' ';
  1552.                  getinfo(info_buf,info_len,info_parm);
  1553.                  if info_len > 0 then
  1554.                  begin
  1555.                     get_user_name := true;
  1556.                     xplib_user.version_no    := 1;
  1557.                     xplib_user.user_name     := info_buf;
  1558.                     xplib_user.user_password := 'MAILPASS';
  1559.                  end;
  1560.               end;  {get_user_name}
  1561.  
  1562.            begin {test_xplib}
  1563.  
  1564.               if get_user_name then
  1565.                  init_xplib(5)
  1566.               else
  1567.                  init_xplib(2);
  1568.  
  1569.               count_xplib(1);
  1570.               count_xplib(2);
  1571.               count_xplib(3);
  1572.  
  1573.               end_xplib;
  1574.  
  1575.            end;  {test_xplib}
  1576.  
  1577.            begin {mainline}
  1578.  
  1579.               test_xplib;
  1580.  
  1581.            end.  {mainline}
  1582.  
  1583.     28
  1584.  
  1585.  
  1586.  
  1587.  
  1588.     _______ _   ______ __ ____________
  1589.     Chapter 7   System SL Installation
  1590.  
  1591.  
  1592.                 _  ____________
  1593.                 ⁿ  Introduction
  1594.                 _  _____
  1595.                 ⁿ  Steps
  1596.  
  1597.  
  1598.     ____________
  1599.     Introduction
  1600.  
  1601.            These  instructions  describe  how to install the XPLIB intrinsics
  1602.            into the system SL on Classic versions of  MPE.   The  job  stream
  1603.            Xplib.Mailjob.Robelle  installs  the XPLIB intrinsics so that they
  1604.            can be used by any program on the system.  Use it either to update
  1605.            the  interface  when  you  receive  a  new version of Xpress or to
  1606.            re-install the interface after an MIT update from  HP.   You  will
  1607.            need  a  small  tape  for a new COLDLOAD tape to contain the XPLIB
  1608.            segment.  You can also install the XPLIB intrinsics in  a  pub  or
  1609.                               _________ ___ _______ __ ___ _
  1610.            group SL.  See the Compiling and Linking on MPE V section.
  1611.  
  1612.  
  1613.     _____
  1614.     Steps
  1615.  
  1616.  
  1617.            1. Make  sure  that  the  Robelle account has been created and all
  1618.               files have been restored.
  1619.  
  1620.            2. Ensure  that  no  one  will  use  the  intrinsics   until   the
  1621.               installation  is  complete.   No  one  can be running a program
  1622.               which calls any XPLIB intrinsic.  Stop all  jobs  and  send  an
  1623.               operator warning.
  1624.  
  1625.                    :showjob
  1626.                    :warn @;please stop for 20 minutes
  1627.                                ___
  1628.                    :abortjob #snnn
  1629.  
  1630.            3. Log on as Manager.Sys if you have not already.
  1631.  
  1632.            4. Either  remove  the  passwords  from  Manager.Sys or modify the
  1633.               first line of the XPLIB job to  include  the  passwords.   Then
  1634.               Stream the job.
  1635.  
  1636.                    :altacct sys;pass=
  1637.                    :altuser manager;pass=
  1638.                    :stream xplib.mailjob.robelle
  1639.  
  1640.                         or
  1641.  
  1642.                                     _______ _   ______ __ ____________
  1643.                                     Chapter 7   System SL Installation     29
  1644.  
  1645.  
  1646.  
  1647.                    :editor
  1648.                    /text xplib.mailjob.robelle
  1649.                    /modify first     {insert passwords into the line}
  1650.                    /keep robtemp     {keep local copy}
  1651.                    /exit
  1652.                    :stream robtemp   {stream local copy}
  1653.                    :purge robtemp    {cleanup after yourself}
  1654.  
  1655.            5. XPLIB  uses  the  Segmenter  to  add  the XPLIB intrinsics into
  1656.               SL.Pub.Sys.  It then requests a tape ("COLDLOAD") to  create  a
  1657.               new  cold  load  tape  containing MPE plus the Xpress interface
  1658.               library.  Mount a tape with a write ring and :REPLY.  Save this
  1659.               tape and use it for any future cold loads.
  1660.  
  1661.            6. If  everything  goes  well, XPLIB prints a final message on the
  1662.               console.
  1663.  
  1664.            7. Replace the Manager.Sys passwords (if removed in step 4 above).
  1665.  
  1666.                                          ________
  1667.                    :altuser manager;pass=password
  1668.                                      ________
  1669.                    :altacct sys;pass=password
  1670.  
  1671.            8. Please save the job listing for future reference.
  1672.  
  1673.            The  XPLIB  intrinsics are now installed and you should be able to
  1674.            use them in your application programs.
  1675.  
  1676.                                                                            30
  1677.  
  1678.  
  1679.  
  1680.                       _____
  1681.                       Index
  1682.  
  1683.  
  1684.  
  1685.  
  1686.                       _
  1687.                       A
  1688.  
  1689.                       access.............................2
  1690.  
  1691.  
  1692.                       _
  1693.                       B
  1694.  
  1695.                       Bring-Forward, number of messages..6
  1696.                       Bulletin Board, number of messages.6
  1697.  
  1698.  
  1699.                       _
  1700.                       C
  1701.  
  1702.                       calling sequence...................2
  1703.                       COBOL example......................20
  1704.                       Cobol3.Qlibsrc.Robelle.............3
  1705.                       compiling..........................3,4
  1706.                       condition code.....................5
  1707.  
  1708.  
  1709.                       _
  1710.                       D
  1711.  
  1712.                       documentation......................1
  1713.  
  1714.  
  1715.                       _
  1716.                       E
  1717.  
  1718.                       error messages.....................17
  1719.  
  1720.  
  1721.                       _
  1722.                       I
  1723.  
  1724.                       In Basket, number of messages......6
  1725.                       installation.......................3
  1726.                       intrinsics.........................5
  1727.                       introduction to XPLIB..............1
  1728.  
  1729.  
  1730.                       _
  1731.                       L
  1732.  
  1733.                       Linkedit...........................4
  1734.                       linking............................3,4
  1735.  
  1736.  
  1737.                       _
  1738.                       M
  1739.  
  1740.                       manuals, printing..................1
  1741.                       messages parameter.................6
  1742.                       mode parameter.....................10
  1743.  
  1744.            _____
  1745.     31     Index
  1746.  
  1747.  
  1748.  
  1749.                       Mode-1.............................10
  1750.                       Mode-2.............................10
  1751.                       Mode-3.............................11
  1752.                       Mode-5.............................11
  1753.  
  1754.  
  1755.                       _
  1756.                       P
  1757.  
  1758.                       Pascal example.....................24
  1759.                       Prep...............................3
  1760.                       Printdoc program...................1
  1761.                       printing manuals...................1
  1762.                       Prose program......................1
  1763.  
  1764.  
  1765.                       _
  1766.                       S
  1767.  
  1768.                       son process........................2
  1769.                       status area........................5
  1770.                       system SL installation.............28
  1771.  
  1772.  
  1773.                       _
  1774.                       U
  1775.  
  1776.                       user name..........................2
  1777.                       user name parameter................14,16
  1778.  
  1779.  
  1780.                       _
  1781.                       W
  1782.  
  1783.                       workspace parameter................2,10
  1784.  
  1785.  
  1786.                       _
  1787.                       X
  1788.  
  1789.                       XPLIB program......................2
  1790.                       Xplib.Mailjob.Robelle..............28
  1791.                       XPLIBCOUNT intrinsic...............6
  1792.                       XPLIBEND intrinsic.................8
  1793.                       XPLIBEXPLAIN intrinsic.............9
  1794.                       XPLIBINIT intrinsic................10
  1795.                       XPLIBUSERFIND intrinsic............14
  1796.                       XPLIBUSERGET intrinsic.............16
  1797.  
  1798.                                                                           iii
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.                                                     ______ _________ _______
  1814.                                                     XPRESS Intrinsic Library
  1815.  
  1816.  
  1817.  
  1818.  
  1819.                                                                     ________
  1820.                                                                     Contents
  1821.  
  1822.  
  1823.  
  1824.                          _______ _   _____
  1825.                          Chapter 1   XPLIB
  1826.  
  1827.                                     Introduction..........................1
  1828.                                     Printing documentation................1
  1829.  
  1830.                          _______ _   _________ ___ _____ __________
  1831.                          Chapter 2   Accessing the XPLIB Intrinsics
  1832.  
  1833.                                     The XPLIB program.....................2
  1834.                                     Xpress user name......................2
  1835.                                     Calling sequence......................2
  1836.                                     COBOL sample file.....................3
  1837.                                     Compiling and linking on MPE V........3
  1838.                                        Using Lib=.........................3
  1839.                                     Compiling and linking on MPE/iX.......4
  1840.                                        User XL files......................4
  1841.  
  1842.                          _______ _   _____ __________
  1843.                          Chapter 3   XPLIB Intrinsics
  1844.  
  1845.                                     Status array..........................5
  1846.                                     Declaration...........................5
  1847.                                     XPLIBCOUNT intrinsic..................6
  1848.                                     XPLIBEND intrinsic....................8
  1849.                                     XPLIBEXPLAIN intrinsic................9
  1850.                                     XPLIBINIT intrinsic...................10
  1851.                                     XPLIBUSERFIND intrinsic...............14
  1852.                                     XPLIBUSERGET intrinsic................16
  1853.  
  1854.                          _______ _   _____ _____ ________
  1855.                          Chapter 4   XPLIB Error Messages.................17
  1856.  
  1857.            ________
  1858.     iv     Contents
  1859.  
  1860.  
  1861.  
  1862.                          _______ _   _____ _______
  1863.                          Chapter 5   COBOL Example........................20
  1864.  
  1865.                          _______ _   ______ _______
  1866.                          Chapter 6   Pascal Example.......................24
  1867.  
  1868.                          _______ _   ______ __ ____________
  1869.                          Chapter 7   System SL Installation
  1870.  
  1871.                                     Introduction..........................28
  1872.                                     Steps.................................28
  1873.  
  1874.                          _____
  1875.                          Index............................................30
  1876.  
  1877.