______ _______ ___ XPRESS Version 3.2 __________ __________ ____ Affordable Electronic Mail ___ ___ __ ____ for the HP 3000 ______ _________ _______ Xpress Intrinsic Library _______ _________ __________ ____ Robelle Solutions Technology Inc. ____ ___ _______ _____ ___ 7360 137 Street, Suite 372 _______ ____ ______ ___ ___ Surrey, B.C. Canada V3W 1A3 __________ _____________ Toll-free: 1.888.robelle ________________ (1.888.762.3553) ______ ____________ Phone: 604.501.2001 ____ ____________ Fax: 604.501.2003 _______ ___________________ E-mail: support@robelle.com ____ _______________ Web: www.robelle.com ____ ____ July 1996 Program and Manual Copyright Robelle Solutions Technology Inc. 1990-2007 ___ Permission is granted to reprint this document (but not for profit), provided that copyright notice is given. XPRESS, QEDIT and SUPRTOOL are trademarks of Robelle Solutions Technology Inc. The following names and marks are companies and trademarks of their respective owners, which designate companies and products not provided by or associated with Robelle or its XPRESS electronic mail, QEDIT editor, and SUPRTOOL database handyman products. HP, HP 3000, IMAGE, LaserJet, MPE, and VPLUS are trademarks of Hewlett-Packard Company. 1 _______ _ _____ Chapter 1 XPLIB _ ____________ ü Introduction _ ________ _____________ ü Printing Documentation ____________ Introduction Welcome to version 3.2 of the Xpress Intrinsic Library. This intrinsic library provides a set of subroutines that can be called from any 3GL programming language. These routines provide these functions: __ ______ _____________ ü You can obtain the number of In Basket, Bring-Forward, or ________ _____ Bulletin Board messages for an Xpress user. ü You can discover whether an Xpress user exists. ü You can specify the Xpress user name and user password for subsequent invocations of Xpress. ________ _____________ Printing Documentation ______ _________ To print extra copies of this user manual (Xpress Intrinsic _______ Library), run the Printdoc program. :run printdoc.pub.robelle;info="xplib.doc.robelle" Printdoc is menu-driven, and very easy to use. Printdoc asks you for information, and if you are not sure of your answer, you can ask for help by typing a question mark (?) and pressing the Return key. Printdoc supports all types of LaserJet printers and regular line printers. You can also print documentation other than user manuals (for example, change notices), if you know the filename. Printdoc uses a message catalog, and requires Prose version 3.1 or later. It will look for these files in the same account as Printdoc. Also, Printdoc will only correctly print Prose documents that use the Output JCWs and the Prose If commands to choose the output device. Note that the table of contents prints last, and must be manually inserted after the title page. 2 _______ _ _________ ___ _____ __________ Chapter 2 Accessing the XPLIB Intrinsics _ ___ _____ _______ ü The XPLIB Program _ ______ ____ ____ ü Xpress User Name _ _______ ________ ü Calling Sequence _ _____ ______ ____ ü COBOL Sample File _ _________ ___ _______ __ ___ _ ü Compiling and Linking on MPE V _ _________ ___ _______ __ ______ ü Compiling and Linking on MPE/iX The XPLIB intrinsics are a set of intrinsics that can be called from compatibility- or native-mode programs. You access XPLIB by calling these intrinsics, just as you would the IMAGE or VPLUS intrinsics. ___ _____ _______ The XPLIB Program The XPLIB intrinsics do not open the Xpress Mail database directly. All requests from the XPLIB intrinsics are processed by the XPLIB program. When you call the XPLIBINIT intrinsics, the Xplib.Mail.Robelle program is created as a son process (unless you have overridden the filename). An error is returned if the XPLIB program cannot be run or if it cannot open the Mail database. ______ ____ ____ Xpress User Name The XPLIB program works like every other Xpress program. If you have already run any other Xpress program, the user name and password from the last Xpress program will be used by the XPLIB program, unless you explicitly specify the user name to the XPLIBINIT intrinsic. You can force the XPLIB program to prompt for the Xpress user name by setting the MailFileStatus JCW to zero before running your program that calls the XPLIB intrinsics. _______ ________ Calling Sequence These steps are required to use the XPLIB intrinsics: 1. A workspace must be declared in your program. This workspace must not change between calls to the various XPLIB intrinsics. 2. The XPLIBINIT intrinsic must be called successfully. 3. Other XPLIB intrinsics can be called as needed. 4. When the program is finished, it can tidy things up by calling the XPLIBEND intrinsic. _______ _ _________ ___ _____ __________ Chapter 2 Accessing the XPLIB Intrinsics 3 _____ ______ ____ COBOL Sample File The file Cobol3.Qlibsrc.Robelle contains COBOL declarations for all parameters required by the XPLIB intrinsics. It also contains template calls to each of the intrinsics. _________ ___ _______ __ ___ _ Compiling and Linking on MPE V You require PH capability in order to use the XPLIB intrinsics. The classic object code for the intrinsics resides in Xplibusl.Mail.Robelle. The intrinsics are installed in SL files. The following commands demonstrate how to compile and prepare your program to use the XPLIB intrinsics. This example assumes that the intrinsics have been installed in the system SL: :cobol example.source :prep $oldpass,example.pub;cap=ph :save example.pub :run example.pub _____ ____ Using Lib= ______ __ ____________ The System SL Installation chapter of the manual tells how to install the intrinsics so that they are available to every program. In doing so, you will not have to run programs with the Lib= parameter. You can also install the intrinsics in an SL file and run your program with Lib=. Here is an example of how to add the XPLIB segment from Xplibusl.Mail to your existing SL file. :run fcopy.pub.sys >from=xplibusl.mail.robelle;to=xplibusl.pub;new >exit :segmenter -buildsl sl.pub,400,4 {fails if you already have an SL} -sl sl.pub -usl xplibusl.pub -addsl xplib -exit You can run your program (e.g., Callxp) with the Lib=P parameter: :cobol callxp.source :prep $oldpass,callxp.program;cap=ph :save callxp.program :run callxp.program;lib=p _______ _ _________ ___ _____ __________ 4 Chapter 2 Accessing the XPLIB Intrinsics _____ Notes The MPE :Prep command prints a warning message when you specify cap=ph. You may ignore this message or specify cap=ia,ba,ph on your :Prep command. If your program requires other capabilities, they should also be specified (e.g., cap=ph,ds). _______ Warning: The XPLIB intrinsics may change over time. The intrinsics should never be installed directly into a program file. They should only be installed into SL files. _________ ___ _______ __ ______ Compiling and Linking on MPE/iX You require PH capability in order to use the XPLIB intrinsics. The intrinsics are installed in XL files. The following commands demonstrate how to compile and link your program to use the XPLIB/iX intrinsics. :cob74xl example.source :link from=$oldpass;to=example.pub;cap=ph :run example.pub;xl='xplibxl.mail.robelle' ____ __ _____ User XL Files You can use MPE/iX's Linkedit command to add the XPLIB intrinsics to your own XL file. For example, :linkedit -xl xl.pub -copyxl from=xplibxl.mail.robelle -exit :run example.pub;xl='xl.pub' 5 _______ _ _____ __________ Chapter 3 XPLIB Intrinsics _ ______ _____ ü Status Array _ ___________ ü Declaration _ __________ _________ ü XPLIBCOUNT Intrinsic _ ________ _________ ü XPLIBEND Intrinsic _ ____________ _________ ü XPLIBEXPLAIN Intrinsic _ _________ _________ ü XPLIBINIT Intrinsic _ _____________ _________ ü XPLIBUSERFIND Intrinsic _ ____________ _________ ü XPLIBUSERGET Intrinsic In this chapter we describe the XPLIB intrinsics in alphabetical order. The parameters for each intrinsic are word arrays (just like IMAGE intrinsic calls). You must include every parameter or pass a dummy variable as a place holder. The condition code is not returned by any XPLIB intrinsic. ______ _____ Status Array The status array is a ten-word array. You can use the standard IMAGE status array or you can declare a custom status parameter for the XPLIB intrinsics. Where it makes sense, the XPLIB intrinsics return error numbers similar to their IMAGE counterparts. If an error occurs, you should call the XPLIBEXPLAIN intrinsic. ___________ Declaration Here is a typical declaration for the status array: 01 xplib-status-area. 05 xplib-cond-word pic s9(4) comp. 88 xplib-stat-ok value zeros. 88 xplib-end-of-users value 15. 88 xplib-no-entry value 17. 05 filler pic s9(4) comp occurs 9 times. _______ _ _____ __________ 6 Chapter 3 XPLIB Intrinsics __________ _________ XPLIBCOUNT Intrinsic __ ______ _____________ ________ _____ Returns the number of In Basket, Bring-Forward, or Bulletin Board messages for either the user set up by the call to XPLIBINIT or for a specific Xpress user. __________ _____ _______ _________ ____ XPLIBCOUNT Workspace, Mode, Status, Messages, User _________ Workspace This is the workspace that was passed to XPLIBINIT. This workspace must not have changed since the call to XPLIBINIT. ____ Mode There is one mode for each of the Xpress basket counts, a single word integer from 1 to 3, or 11 to 13. Modes 1 to 3 ignore the user parameter and use the user set up by the call to XPLIBINIT. If you add ten to the mode (i.e., modes 11, 12, and 13), the same information is returned, but the count is for the user specified in the user parameter. __ ______ Modes 1 and 11. Return the number of In Basket messages. _____________ Modes 2 and 12. Return the number of Bring-Forward messages. ________ _____ Modes 3 and 13. Return the number of Bulletin Board messages that the user has not read. For modes 11, 12, and 13, the user set by XPLIBINIT must be Helpman. This avoids any potential security problems, since Helpman has access to all Xpress users. ______ Status A ten-word array of 16-bit integers. The return value of the first word will be zero if the call to XPLIBCOUNT is successful. ________ Messages The number of messages are returned to this variable, a 16-bit integer: 01 xplib-no-messages pic s9(4) comp. _______ _ _____ __________ Chapter 3 XPLIB Intrinsics 7 ____ User The user name for whom to return the number of messages. This parameter is only used for modes 11, 12, and 13. The user name must be declared as follows: 01 xplib-user-name pic x(26). _______ Example __ ______ This example returns the number of In Basket messages for the user set up by the call to XPLIBINIT. call "XPLIBCOUNT" using xplib-workspace xplib-mode1 xplib-status-area xplib-no-messages xplib-dummy-arg. if not xplib-stat-ok then perform 98-xplib-error _____________ This example returns the number of Bring-Forward messages for the Xpress user "RON JONES". The example assumes that Helpman was set up as the XPLIB user in the call to XPLIBINIT. move "ron jones" to xplib-user-name. call "XPLIBCOUNT" using xplib-workspace xplib-mode12 xplib-status-area xplib-no-messages xplib-user-name. if not xplib-stat-ok then perform 98-xplib-error _____ Notes __ ______ Many applications may only need the number of In Basket messages. This is one reason why not all of the basket counts are returned in a single call to XPLIBCOUNT. The other reason is that the number of disc accesses required varies according to each mode. Here is the summary for each mode: Mode 1 or 11. One disc access. Mode 2 or 12. Two disc accesses plus the number of visible _____________ Bring-Forward messages. Mode 3 or 13. Two disc accesses plus the number of unread ________ _____ Bulletin Board messages. _______ _ _____ __________ 8 Chapter 3 XPLIB Intrinsics ________ _________ XPLIBEND Intrinsic Shuts down the Xpress intrinsic library. This terminates the XPLIB program and reinitializes the workspace parameter. __________ _____ _______ _____ XPLIBEND Workspace, Mode, Status, Dummy _________ Workspace This is the workspace that was passed to XPLIBINIT. This workspace must not have changed since the call to XPLIBINIT. ____ Mode The mode, a 16-bit integer, must contain a value of one. ______ Status A ten-word array of 16-bit integers. The return value of the first word will be zero if the call to XPLIBEND is successful. _____ Dummy This is a dummy parameter and it may contain anything. _______ Example call "XPLIBEND" using xplib-workspace xplib-mode1 xplib-status-area xplib-dummy-arg. if not xplib-stat-ok then perform 98-xplib-error. _______ _ _____ __________ Chapter 3 XPLIB Intrinsics 9 ____________ _________ XPLIBEXPLAIN Intrinsic Prints a three-line message on $Stdlist which describes the results of an XPLIB intrinsic call based on information in the status array. ______ XPLIBEXPLAIN status ______ Status The status is a ten-word array of 16-bit integers used to call any XPLIB intrinsic. _______ _ _____ __________ 10 Chapter 3 XPLIB Intrinsics _________ _________ XPLIBINIT Intrinsic Initializes the Xpress intrinsic library. Depending on the mode, you may also use the XPLIBINIT intrinsic to specify the run-parameters for the XPLIB program and the Xpress user name to use for subsequent calls to the XPLIB intrinsics. __________ _____ _______ ________ _________ _____ XPLIBINIT Workspace, Mode, Status, RunParm, UserParm, Dummy _________ Workspace The workspace is used by the XPLIB intrinsics to store global information. This workspace must not change between calls to XPLIBINIT and any of the other XPLIB intrinsics. The COBOL declaration and initial values for the workspace are as follows: 01 xplib-workspace. 05 xplib-version-no pic s9(4) comp value 1. 05 filler pic x(10) value spaces. ____ Mode This is a single word integer, and may have the value 1, 2, 3, or 5. ______ Mode-1 Initialize the Xpress intrinsic library. Use Xplib.Mail.Robelle for processing. If no Xpress program has been run, XPLIBINIT will prompt for the Xpress user name and user password. You must pass a dummy parameter for the run-parameter and the user-parameter. call "XPLIBINIT" using xplib-workspace xplib-mode1 xplib-status-area xplib-dummy-arg xplib-dummy-arg xplib-dummy-arg. if not xplib-stat-ok then perform 98-xplib-error. ______ Mode-2 Initialize the library, but specify the name and run-parameters for the XPLIB program. With Mode-2, you must pass a fourth parameter to XPLIBINIT (see below for how to declare the run-parameters). Pass a dummy parameter for the user-parameter. _______ _ _____ __________ Chapter 3 XPLIB Intrinsics 11 call "XPLIBINIT" using xplib-workspace xplib-mode2 xplib-status-area xplib-run-parm xplib-dummy-arg xplib-dummy-arg. if not xplib-stat-ok then perform 98-xplib-error. ______ Mode-3 You can specify which Xpress user the XPLIB intrinsics should use with Mode-3. With Mode-3, you must pass a fifth parameter to XPLIBINIT (see below for the user-parameter declaration). You must pass a dummy parameter for the run-parameter. call "XPLIBINIT" using xplib-workspace xplib-mode3 xplib-status-area xplib-dummy-arg xplib-user-parm xplib-dummy-arg. if not xplib-stat-ok then perform 98-xplib-error. ______ Mode-5 With Mode-5, you can specify the XPLIB program run-parameters, and the Xpress user name to use with the XPLIB library. Effectively, this combines Mode-2 and Mode-3. For Mode-5, you must pass both the XPLIB run-parameter and user-parameter: call "XPLIBINIT" using xplib-workspace xplib-mode5 xplib-status-area xplib-run-parm xplib-user-parm xplib-dummy-arg. if not xplib-stat-ok then perform 98-xplib-error. ______ Status A ten-word array of 16-bit integers. The return value of the first word will be zero if the call to XPLIBINIT is successful. Twenty will be returned if no Xpress user is active, and you do not specify an Xpress user to XPLIBINIT, and no Xpress user name is specified to the XPLIB program. _______ _ _____ __________ 12 Chapter 3 XPLIB Intrinsics ___ _________ Run Parameter When using Mode-2 or Mode-5, you must pass a parameter describing how you want to run the XPLIB program. It has the following COBOL declaration: 01 xplib-run-parms. 05 xplib-run-version pic s9(4) comp value 1. 05 xplib-run-progname pic x(36) value "xplib.mail.dev". 05 xplib-run-lib pic s9(4) comp value 0. 05 xplib-run-parm pic s9(4) comp value 2. _________________ xplib-run-version must have the value one. __________________ xplib-run-progname is the name of the actual XPLIB program. In our example, it is Xplib.Mail.Dev. _____________ xplib-run-lib is the library search to use when running the XPLIB program. The valid values are as follows: 0. Lib=S 1. Lib=P 2. Lib=G ______________ xplib-run-parm is the Parm= value to use when running the XPLIB program. If you have moved the Xpress Mail database, you ______________ will need to set the xplib-run-parm to 2. If your Mail database is in the Maildb group of the Robelle account, you ______________ should set xplib-run-parm to zero. ____ _________ User Parameter When using Mode-3 or Mode-5, you must pass a parameter describing the Xpress user name and user password. This parameter has the following COBOL declaration: 01 xplib-user-parms. 05 xplib-user-version pic s9(4) comp value 1. 05 xplib-user-name pic x(26) value spaces. 05 xplib-user-password pic x(20) value spaces. __________________ xplib-user-version must have the value one. _______________ xplib-user-name is the name of the Xpress user to use when invoking the XPLIB program. If the name is invalid, the XPLIB program will prompt for a valid name. ___________________ xplib-user-password is the Xpress user password to use when invoking the XPLIB program. If the password is invalid, the XPLIB program will prompt for a valid one. _______ _ _____ __________ Chapter 3 XPLIB Intrinsics 13 _____ Dummy This is a dummy parameter and it may contain anything. _____ Notes The XPLIBINIT intrinsic creates the XPLIB program as a son process. The XPLIB program must open the Xpress Mail database, open other files, obtain the user name, and execute other initializations. This involves a lot of overhead. We have designed the XPLIB intrinsics assuming that you will call XPLIBINIT once at the start of your program. You cannot call any other XPLIB intrinsic until you have successfully called the XPLIBINIT intrinsic. _______ _ _____ __________ 14 Chapter 3 XPLIB Intrinsics _____________ _________ XPLIBUSERFIND Intrinsic Checks the Mail database to see if a user name exists or not. __________ _____ _______ ____ XPLIBUSERFIND Workspace, Mode, Status, User _________ Workspace This is the workspace that was passed to XPLIBINIT. This workspace must not have changed since the call to XPLIBINIT. ____ Mode There are two modes for calling XPLIBUSERFIND, one for exact matches and one for partial matches: 1. See if the passed user name exists. The user name must be an exact match to an existing Xpress user name. 2. Find all users that match the passed user name. The number of matching users is returned in the status array. ______ Status A ten-word array of 16-bit integers. The return value of the first word will be zero if the user name passed to XPLIBUSERFIND exists. If the user name does not exist, seventeen is returned in the condition word. If XPLIBUSERFIND was called with Mode-2, the number of matching user names is returned in status-words five and six (these are the same words to which IMAGE returns the chain length after a call to DBFIND). ____ User This is the Xpress user name that you are looking for. This must be a twenty-six character buffer padded with spaces. The user name can be in lower case, upper case, or mixed case. For Mode-1, the user name must be spelled in full, just as you would type it into Xpress. For Mode-2, it can be any leading characters in an Xpress user name and must not be blank. 01 user-name pic x(26) value "joe smith". _______ _ _____ __________ Chapter 3 XPLIB Intrinsics 15 _______ Example call "XPLIBUSERFIND" using xplib-workspace xplib-mode1 xplib-status-area user-name. if not xplib-stat-ok then perform 98-xplib-error. _______ _ _____ __________ 16 Chapter 3 XPLIB Intrinsics ____________ _________ XPLIBUSERGET Intrinsic XPLIBUSERGET returns all Xpress user names that matched a partial user name from a call to XPLIBUSERFIND. __________ _____ _______ ____ XPLIBUSERGET Workspace, Mode, Status, User _________ Workspace This is the workspace that was passed to XPLIBINIT. This workspace must not have changed since the call to XPLIBINIT. ____ Mode The mode must be one. ______ Status A ten-word array of 16-bit integers. The return value of the first word will be zero while there are still user names to return. After the last user name has been returned, the first word is set to fifteen (the same value IMAGE uses for end-of-chain). ____ User The next Xpress user name. This must be a twenty-six character buffer. XPLIBUSERGET always pads the user name with spaces. 01 user-name pic x(26). _______ Example call "XPLIBUSERGET" using xplib-workspace xplib-mode1 xplib-status-area user-name. if not xplib-stat-ok and not xplib-end-of-users then perform 98-xplib-error. 17 _______ _ _____ _____ ________ Chapter 4 XPLIB Error Messages XPLIB returns error numbers in the status parameter. Each error is associated with an error number. Positive error numbers indicate warnings and negative error numbers indicate fatal problems. The following are the error numbers, descriptions, and causes that can be returned by any XPLIB intrinsic. ____ _______ ____ -20: Invalid mode The mode passed to an XPLIB intrinsic is not valid. Check that the mode is being passed as the second parameter and ensure that a valid value is being specified. ____ _______ _______ ______ _ -21: Invalid version number n The version number in the workspace parameter does not have the value one. Ensure that the workspace is declared correctly. The first field in the workspace must be a 16-bit integer with the value one. ____ _____________ _____ -22: Createprocess error A call to the createprocess intrinsic has failed. This message is followed by an additional line showing the actual createprocess error message. When calling XPLIBINIT with Mode-2 or Mode-5, be __________________ sure that the xplib-run-progname field is correct. The reasons that this error may occur are as follows: ü The program Xplib.Mail.Robelle does not exist. __________________ ü The program filename specified in the xplib-run-progname field is not spelled correctly. ü You forgot to :Prep or :Link your program with cap=ph. ü Your machine is out of resources to run more processes. ____ _______ _______ ______ ___ ___ __________ _ -23: Invalid version number for run parameters n ___ __________ The version number specified in the run parameters does not have the value one. The version number passed to XPLIBINIT is printed. Ensure that the version number of the run-parameter is the first field and that it is declared as a 16-bit integer with the value one. _______ _ _____ _____ ________ 18 Chapter 4 XPLIB Error Messages ____ _______ ___ _______ _ -24: Invalid run library n The library field of the run-parameters does not have the value 0, 1, or 2. The actual value passed to XPLIBINIT is printed. Ensure that the run-parameter library field is a 16-bit integer with a valid value. ____ __ ______ ___ _______ ___ _______ ____ -25: No active son process for sending mail This error should never occur. If it does, please report it to Robelle Consulting Ltd. ____ ______ __ ________ ___ _______ -26: Unable to activate son process This error should never occur. If it does, please report it to Robelle Solutions Technology Inc. ____ _____ _______ __________ -27: Xplib program terminated This error occurs whenever the XPLIB program terminates. When calling XPLIBINIT, the most common reason for this error is that XPLIB could not open the Password file or the Mail database. For the other intrinsics, this error usually indicates that the XPLIB program failed with a fatal error. ____ ________ ______ __ ________ _______ _ -28: Sendmail failed -- sendmail status: n This error should never occur. If it does, please report it to Robelle Solutions Technology Inc. ____ ___________ ______ __ ___________ _______ _ -29: Receivemail failed -- receivemail status: n This error should never occur. If it does, please report it to Robelle Solutions Technology Inc. ____ _______ ________ ___________ _____ _ -30: Invalid internal transaction type: n This error should never occur. If it does, please report it to Robelle Solutions Technology Inc. ____ ______ __ ____ _____ ___ _______ -31: Unable to kill Xplib son process This error should never occur. If it does, please report it to Robelle Solutions Technology Inc. _______ _ _____ _____ ________ Chapter 4 XPLIB Error Messages 19 ____ _______ _______ ______ ___ ____ __________ _ -32: Invalid version number for user parameters n ____ __________ The version number specified in the user parameters does not have the value one. The version number passed to XPLIBINIT is printed. Ensure that the user-parameter version number is the first field and that it is declared as a 16-bit integer with the value one. ____ ____ __ ______ _______ ______ _ _ -33: Call to PUTJCW failed. Status = n This error should never occur. If it does, please report it to Robelle Solutions Technology Inc. ____ _________ _________ ___ ____ ________ -34: Workspace parameter has been modified Between calls to the XPLIB intrinsics, the XPLIB workspace has been changed. Ensure that the workspace has not been overwritten by calls to other subroutines. You must also ensure that the workspace is a global data structure. ____ _______ ____ __ ___ ____ ___ _____ ___ ___ ___ __ -35: Helpman must be the user for modes 11, 12, and 13 When calling XPLIBCOUNT with modes 11, 12, or 13, the user specified for the XPLIB program (either explicitly in XPLIBINIT or when the XPLIB program prompts for the Xpress user name) must be Helpman. ___ ___ __ ____ _____ 15: End of user names Returned when XPLIBUSERGET has no more user names to return. ___ __ _____ _____ 17: No entry found Returned when XPLIBCOUNT or XPLIBUSERFIND cannot find the requested Xpress user name. For Mode-2 calls to XPLIBUSERFIND, there was no Xpress user that matched the name passed to XPLIBUSERFIND. ___ __ ____ _________ ___ ___ _____ _______ 20: No user specified for the XPLIB program No valid user name was specified to the XPLIB program. This error is returned by XPLIBINIT when the XPLIB program prompts for a user name and none is entered. 20 _______ _ _____ _______ Chapter 5 COBOL Example __ ______ The following program displays the number of In Basket, _____________ ________ _____ Bring-Forward, and Bulletin Board messages for an Xpress user. This example also shows how to specify a non-standard name for the XPLIB program. An Info= string will be used as the Xpress user name. If no Info= string is specified, we either use an Xpress user name that was entered previously or the XPLIB program prompts for a user name. $control nolist $control source,errors=10 identification division. program-id. testcob. author. David Greer, Robelle Solutions Technology Inc. date-written. Jan 2, 1991. security. Copyright Robelle Solutions Technology Inc. 1991-2007. remarks. ************************************************************ * * * testcob - test xplib intrinsics. * * * * version: 1.0 * * purpose: * * * * General-purpose program to test the XPLIB intrinsics. * * * * Demonstrates that you can call all XPLIB routines from * * COBOL in CM and NM. * * * ************************************************************ environment division. configuration section. special-names. top is new-page. $page "constants" data division. working-storage section. 01 true-value pic x value "T". 01 false-value pic x value "F". $page "variables" 01 input-line pic x(80). 88 answer-spaces value spaces. 01 jcw-name pic x(255). 01 jcw-status pic s9(4) comp. _______ _ _____ _______ Chapter 5 COBOL Example 21 01 info-string pic x(80) value spaces. 01 info-length pic s9(4) comp value 80. 01 info-result pic s9(4) comp. 01 parm-value pic s9(4) comp. $page "xplib- variables" 01 xplib-mode pic s9(4) comp. 01 xplib-mode1 pic s9(4) comp value 1. 01 xplib-dummy-arg pic s9(4) comp. 01 xplib-status-area. 05 xplib-cond-word pic s9(4) comp. 88 xplib-stat-ok value zeros. 88 xplib-end-of-users value 15. 88 xplib-no-entry value 17. 05 filler pic s9(4) comp occurs 3 times. 05 xplib-user-count pic s9(9) comp. 05 filler pic s9(4) comp occurs 4 times. 01 xplib-workspace. 05 xplib-version-no pic s9(4) comp value 1. 05 filler pic x(10) value spaces. 01 xplib-run-parms. 05 xplib-run-version pic s9(4) comp value 1. 05 xplib-run-progname pic x(36) value "xplib.mail.robelle". 05 xplib-run-lib pic s9(4) comp value 0. 05 xplib-run-parm pic s9(4) comp value 3. 01 xplib-user-parms. 05 xplib-user-version pic s9(4) comp value 1. 05 xplib-user-name pic x(26) value spaces. 05 xplib-user-password pic x(20) value spaces. 01 xplib-no-messages pic s9(4) comp. 01 display-no-messages pic z9. $page "[00] mainline" procedure division. 00-main section. perform 00-05-get-user-name. perform 00-10-init-xplib. perform 00-20-count-messages varying xplib-mode from 1 by 1 _______ _ _____ _______ 22 Chapter 5 COBOL Example until xplib-mode > 3. perform 00-90-end-xplib. go to 00-main-exit. 00-05-get-user-name. call intrinsic "GETINFO" using info-string info-length parm-value giving info-result. if info-length > 0 and info-result = 0 then move info-string to xplib-user-name move "MAILPASS" to xplib-user-password move 5 to xplib-mode else move 2 to xplib-mode. 00-10-init-xplib. call "XPLIBINIT" using xplib-workspace xplib-mode xplib-status-area xplib-run-parms xplib-user-parms xplib-dummy-arg. if not xplib-stat-ok then perform 98-xplib-error. 00-20-count-messages. call "XPLIBCOUNT" using xplib-workspace xplib-mode xplib-status-area xplib-no-messages xplib-dummy-arg. if not xplib-stat-ok then perform 98-xplib-error else perform 00-30-display-count perform 00-40-update-jcw. 00-30-display-count. move xplib-no-messages to display-no-messages. if xplib-mode = 1 then display "In Basket: ", display-no-messages else if xplib-mode = 2 then display "Bring-Forward: ", display-no-messages else if xplib-mode = 3 then display "Bulletin Board: ", display-no-messages. 00-40-update-jcw. if xplib-mode = 1 then move "INBASKET " to jcw-name _______ _ _____ _______ Chapter 5 COBOL Example 23 else if xplib-mode = 2 then move "BRINGFORWARD " to jcw-name else if xplib-mode = 3 then move "BULLETINBOARD " to jcw-name. call intrinsic "PUTJCW" using jcw-name xplib-no-messages jcw-status. if jcw-status <> 0 then display "Putjcw failed. Status = ", jcw-status call intrinsic "QUIT" using jcw-status. 00-90-end-xplib. call "XPLIBEND" using xplib-workspace xplib-mode1 xplib-status-area xplib-dummy-arg. if not xplib-stat-ok then perform 98-xplib-error. 00-main-exit. goback. $page "[98] xplib-error" 98-xplib-error section. call "XPLIBEXPLAIN" using xplib-status-area. call intrinsic "QUIT" using xplib-cond-word. 98-xplib-error-exit. goback. 24 _______ _ ______ _______ Chapter 6 Pascal Example The following Pascal program works exactly like our example COBOL program. This example program compiles and runs in native-mode ________ under MPE/iX, but you must delete the declaration for shortint. $list off$ program driver(input,output); type longint = integer; shortint = -32768 .. +32767; {Remove for MPE/iX} type_workspace = record version_no : shortint; filler : array[1..5] of shortint; end; type_status_area = array[1..10] of shortint; type_mode = shortint; type_run_parm = record version_no : shortint; progname : packed array [1..36] of char; run_lib : shortint; run_parm : shortint; end; type_user_parm = record version_no : shortint; user_name : packed array [1..26] of char; user_password : packed array [1..20] of char; end; type_dummy_arg = array[1..2] of shortint; $check_formal_parm 2$ $check_actual_parm 2$ procedure xplibinit(var xplib_workspace : type_workspace; var xplib_mode : type_mode; var xplib_status_area: type_status_area; var xplib_run_parm : type_run_parm; var xplib_user_parm : type_user_parm; var xplib_dummy_arg : type_dummy_arg ); external spl; procedure xplibcount(var xplib_workspace : type_workspace; var xplib_mode : type_mode; _______ _ ______ _______ Chapter 6 Pascal Example 25 var xplib_status_area: type_status_area; var xplib_no_messages: shortint; var xplib_dummy_arg : type_dummy_arg ); external spl; procedure xplibend(var xplib_workspace : type_workspace; var xplib_mode : type_mode; var xplib_status_area: type_status_area; var xplib_dummy_arg : type_dummy_arg ); external spl; procedure xplibexplain (var xplib_status_area : type_status_area ); external spl; procedure quit; intrinsic; procedure putjcw; intrinsic; procedure getinfo; intrinsic; $check_formal_parm 3$ procedure test_xplib; var xplib_workspace : type_workspace; xplib_run_parm : type_run_parm; xplib_status_area : type_status_area; xplib_user : type_user_parm; procedure fatal_xplib_error; begin xplibexplain(xplib_status_area); quit(xplib_status_area[1]); end; {fatal_xplib_error} procedure init_xplib(xplib_mode: type_mode); var dummy_arg_user : type_user_parm; dummy_arg : type_dummy_arg; begin xplib_workspace.version_no := 1; xplib_run_parm.version_no := 1; xplib_run_parm.progname := 'xplib.mail.robelle'; xplib_run_parm.run_lib := 0; xplib_run_parm.run_parm := 2; xplibinit(xplib_workspace ,xplib_mode ,xplib_status_area ,xplib_run_parm ,xplib_user ,dummy_arg ); if xplib_status_area[1] <> 0 then fatal_xplib_error; end; {init_xplib} _______ _ ______ _______ 26 Chapter 6 Pascal Example procedure print_count(xplib_mode: type_mode; count : shortint ); begin case xplib_mode of 1 : write('In Basket '); 2 : write('Bring Forward '); 3 : write('Bulletin Board'); end; writeln(' = ',count:1); end; {print_count} procedure update_jcw(xplib_mode: type_mode; count : shortint); var jcwname : packed array[1..255] of char; jcw_status : shortint; begin case xplib_mode of 1 : jcwname := 'INBASKET'; 2 : jcwname := 'BRINGFORWARD'; 3 : jcwname := 'BULLETINBOARD'; end; putjcw(jcwname,count,jcw_status); if jcw_status <> 0 then begin writeln('PUTJCW failed with status = ',jcw_status:1); quit(jcw_status); end; end; {update_jcw} procedure count_xplib(xplib_mode : shortint); var xplib_messages : shortint; dummy_arg : type_dummy_arg; begin xplibcount(xplib_workspace ,xplib_mode ,xplib_status_area ,xplib_messages ,dummy_arg ); if xplib_status_area[1] <> 0 then fatal_xplib_error; print_count(xplib_mode,xplib_messages); update_jcw(xplib_mode,xplib_messages); end; {count_xplib} procedure end_xplib; var xplib_mode : type_mode; dummy_arg : type_dummy_arg; begin xplib_mode := 1; xplibend(xplib_workspace _______ _ ______ _______ Chapter 6 Pascal Example 27 ,xplib_mode ,xplib_status_area ,dummy_arg ); if xplib_status_area[1] <> 0 then fatal_xplib_error; end; {end_xplib} function get_user_name : boolean; var info_buf : packed array [1..26] of char; info_len : shortint; info_parm : shortint; begin {get_user_name} info_len := 26; info_buf := ' '; getinfo(info_buf,info_len,info_parm); if info_len > 0 then begin get_user_name := true; xplib_user.version_no := 1; xplib_user.user_name := info_buf; xplib_user.user_password := 'MAILPASS'; end; end; {get_user_name} begin {test_xplib} if get_user_name then init_xplib(5) else init_xplib(2); count_xplib(1); count_xplib(2); count_xplib(3); end_xplib; end; {test_xplib} begin {mainline} test_xplib; end. {mainline} 28 _______ _ ______ __ ____________ Chapter 7 System SL Installation _ ____________ ü Introduction _ _____ ü Steps ____________ Introduction These instructions describe how to install the XPLIB intrinsics into the system SL on Classic versions of MPE. The job stream Xplib.Mailjob.Robelle installs the XPLIB intrinsics so that they can be used by any program on the system. Use it either to update the interface when you receive a new version of Xpress or to re-install the interface after an MIT update from HP. You will need a small tape for a new COLDLOAD tape to contain the XPLIB segment. You can also install the XPLIB intrinsics in a pub or _________ ___ _______ __ ___ _ group SL. See the Compiling and Linking on MPE V section. _____ Steps 1. Make sure that the Robelle account has been created and all files have been restored. 2. Ensure that no one will use the intrinsics until the installation is complete. No one can be running a program which calls any XPLIB intrinsic. Stop all jobs and send an operator warning. :showjob :warn @;please stop for 20 minutes ___ :abortjob #snnn 3. Log on as Manager.Sys if you have not already. 4. Either remove the passwords from Manager.Sys or modify the first line of the XPLIB job to include the passwords. Then Stream the job. :altacct sys;pass= :altuser manager;pass= :stream xplib.mailjob.robelle or _______ _ ______ __ ____________ Chapter 7 System SL Installation 29 :editor /text xplib.mailjob.robelle /modify first {insert passwords into the line} /keep robtemp {keep local copy} /exit :stream robtemp {stream local copy} :purge robtemp {cleanup after yourself} 5. XPLIB uses the Segmenter to add the XPLIB intrinsics into SL.Pub.Sys. It then requests a tape ("COLDLOAD") to create a new cold load tape containing MPE plus the Xpress interface library. Mount a tape with a write ring and :REPLY. Save this tape and use it for any future cold loads. 6. If everything goes well, XPLIB prints a final message on the console. 7. Replace the Manager.Sys passwords (if removed in step 4 above). ________ :altuser manager;pass=password ________ :altacct sys;pass=password 8. Please save the job listing for future reference. The XPLIB intrinsics are now installed and you should be able to use them in your application programs. 30 _____ Index _ A access.............................2 _ B Bring-Forward, number of messages..6 Bulletin Board, number of messages.6 _ C calling sequence...................2 COBOL example......................20 Cobol3.Qlibsrc.Robelle.............3 compiling..........................3,4 condition code.....................5 _ D documentation......................1 _ E error messages.....................17 _ I In Basket, number of messages......6 installation.......................3 intrinsics.........................5 introduction to XPLIB..............1 _ L Linkedit...........................4 linking............................3,4 _ M manuals, printing..................1 messages parameter.................6 mode parameter.....................10 _____ 31 Index Mode-1.............................10 Mode-2.............................10 Mode-3.............................11 Mode-5.............................11 _ P Pascal example.....................24 Prep...............................3 Printdoc program...................1 printing manuals...................1 Prose program......................1 _ S son process........................2 status area........................5 system SL installation.............28 _ U user name..........................2 user name parameter................14,16 _ W workspace parameter................2,10 _ X XPLIB program......................2 Xplib.Mailjob.Robelle..............28 XPLIBCOUNT intrinsic...............6 XPLIBEND intrinsic.................8 XPLIBEXPLAIN intrinsic.............9 XPLIBINIT intrinsic................10 XPLIBUSERFIND intrinsic............14 XPLIBUSERGET intrinsic.............16 iii ______ _________ _______ XPRESS Intrinsic Library ________ Contents _______ _ _____ Chapter 1 XPLIB Introduction..........................1 Printing documentation................1 _______ _ _________ ___ _____ __________ Chapter 2 Accessing the XPLIB Intrinsics The XPLIB program.....................2 Xpress user name......................2 Calling sequence......................2 COBOL sample file.....................3 Compiling and linking on MPE V........3 Using Lib=.........................3 Compiling and linking on MPE/iX.......4 User XL files......................4 _______ _ _____ __________ Chapter 3 XPLIB Intrinsics Status array..........................5 Declaration...........................5 XPLIBCOUNT intrinsic..................6 XPLIBEND intrinsic....................8 XPLIBEXPLAIN intrinsic................9 XPLIBINIT intrinsic...................10 XPLIBUSERFIND intrinsic...............14 XPLIBUSERGET intrinsic................16 _______ _ _____ _____ ________ Chapter 4 XPLIB Error Messages.................17 ________ iv Contents _______ _ _____ _______ Chapter 5 COBOL Example........................20 _______ _ ______ _______ Chapter 6 Pascal Example.......................24 _______ _ ______ __ ____________ Chapter 7 System SL Installation Introduction..........................28 Steps.................................28 _____ Index............................................30