Element

Description

Number

0

Constant

vxOpenConnectionCmd

Input Arguments

1 = Script - Connection Script from MSD object.

Output Arguments

1 = Handle - Base Connection Handle.

Operation

This message is handled by the Vpmv20.dll library functions and the Server protocol. It is used to start-up communications, establishing an initial connection between the client and the server. Each subsequent client message will include the connection handle returned by the server as the result of a connection being made.  For the rest of the messages, it is assumed that any message sent by the client is prefaced with the connection handle.

Element

Description

Number

1

Constant

vxLoginServerCmd

Input Arguments

1 = User - User ID Name.

2 = Password - Optional password for account access.

Output Arguments

1 = Server Handle - The  Server Connection number for this session.

Operation

The server program reads the CONNECTIONS record from the VSCONTROL file (in the server account). Tries to locate the user in the existing connections. If the User Name is not found, the server will see if any connections are available (i.e. it will verify the total number of licensed connections is not exceeded).

If there is a connection available, the program retrieves the User Record from the VSUSERS file. If the user is not defined, the process returns an error. The password sent by the client is checked against the password on the User record. If the passwords are not the same, an error is returned.

Element

Description

Number

2

Constant

vxOpenDatabaseCmd

Input Arguments

1 = Server Handle - Server Number.

2 = Account Name - Pick Account Name (Database Name) to Open (set pointer to).

Output Arguments

1 = Database Handle - The Number assigned to this database for this session.

Operation

The server program first verifies that the Server Handle passed matches the current server process. It gets the Account Name from VSDATABASE file (mapping file). If the account is found, the process checks to make sure the connection/user has the correct permission codes. The permission codes needed to open a database are: D - Read Definitions and R - Read Data.

Element

Description

Number

49

Constant

vxCloseDatabaseCmd

Input Arguments

2 = Database Handle - The Number assigned to this database for this session.

Output Arguments

None

Operation

The server program firsts verifies the database number passed is an active database number. It then goes through and UN-Locks all locked files (on the host, if any). It also cleans up and/or clears all associated internal (server) variables associated with that database.  It then releases the assigned database number.

Element

Description

Number

98

Constant

vxLogOffServerCmd

Input Arguments

1 = Server Handle - The number assigned for this server session.

Output Arguments

None

Operation

The program verifies the server number passed is the correct and active server number. The program then goes through each currently active database and UN-Locks the files that may be locked. The connection is then deleted from CONNECTIONS record in the VSCONTROL file. This then allows another connection.

Element

Description

Number

99

Constant

vxCloseConnectionCmd

Input Arguments

1 = Handle - Base Connection Handle.

Output Arguments

None

Operation

This message is handled by the Vpmv20.dll library functions and the Server protocol. It closes the base connection to the server, shutting down the serial or network communication protocol in use. It then releases the base connection handle for use by other connections.

Element

Description

Number

3

Constant

VxOpenQueryCmd

Input Arguments

1 = Server Handle - The number assigned for this server session.  

2 = Query Type – 0 for a Record Query, non-zero for an Action Query.

3 = Database Handle - The number assigned to the database (Pick account) during the open database function.

4 = Table List - A multi-valued list of actual table (file) names.

5 = Table Flags - A multi-valued list of table (file) operations: 1 for Selecting Records; 2 for Updating Records; 4 for Adding New Records; 8 for Deleting Records; 16 for Locking Records; 32 for Locking records at read  time; 128 for Re-reading records before update lock. Note: the table flags usually would come as one number by just adding up the data (e.g. a flag of 47 could only be obtained by passing a 1, 2, 4, 8, 32).

6 = Field List - A sub-valued list of actual field names correlated with the multi-valued list of actual table names in the Table List.

7 = Select Fields - A multi-valued list of selection field references and criteria:  Table number; Field number; operator number (0 for =; 1 for not equal, …); logical number (0 for none, 1 for or, 2 for and); not number (0 for off, 1 for on); lp (left parenthesis) number; rp (right parenthesis) number.

8 = Join Fields - A multi-valued list of join field references: Table number: Field number; Table number: Field number; Join Type; Join Operator. Join Types: 1 (inner), 2 (left outer), 3 (right outer). Join Operator: 0(=), 1(<>), 2(<), 3(>), 4(<=), 5(>=).

9 = Order by Fields - A multi-valued of sort field references and sort order: Table Number: Field Number: Order (0 ascending, 1 descending).

10 = Extract Fields - A multi-valued list of read/extract field references: Table Number: Field Number.

11 = Update Fields - A multi-valued list of write/update field references: Table Number: Field Number.

12 = Insert Fields - A multi-valued list of write/insert field references: Table Number: Field Number.

Output Arguments

1 = Query Handle - The number assigned to the defined query.

Operation

The server program first goes through and retrieves the first available query number (a maximum of 50 queries are allowed). It then verifies that the database number sent is accurate.  The program goes through each of the tables (files) defined and will do the following:

1) Check to see if the table (file) has been mapped: Verify the table is defined in the VSDATABASE file (key is Database Name \ Table Name).

2) Validate the permissions: Must return at a minimum the permissions of  D Read Definitions and R Read Data.

3) Open the dictionary and the data portion (remotely from the MVSERVER account) file: Find the next available file number (a maximum of 100 files are allowed).

4) Check to see if this file has been defined as Virtual Table in the mapping process. A Virtual Table may be a sub-valued or a multi-valued definition.

5) Go through the associated fields for this table and do the following:

1. Determine the next available field number (a maximum of 300 fields are allowed).

2. Validate whether the field has already been mapped: Verify the field is defined in the VSDATABASE file (key is Database Name \ Table Name \ Field Name).

3. Validate the permission for this field is at least an R Read Data.

4. mapped field definitions.

The server program then checks to see if any Select Fields were passed by the client.  If there were select fields passed, the program does the following:

1) Builds up an internal variable called FL.SELECT. This variable is a dimensioned array based (the dimension part) on the file number.  It will be updated with the following multi-valued information:

1. The internal field number (this will reference which internal FDEFS this select field is associated with)

2. The field number passed from the client.

3. The operator number passed by the client.

4. The logical number passed by the client.

5. The not number passed by the client.

6. The lp number passed by the client.

7. The rp number passed by the client.

8. The query number defined for this query.

9. The selection number passed by the client (i.e. the first, or second, or third, etc. select passed for this query by the client).

10. The type of virtual table associated with this selection. The type may be multi valued or sub valued.

2) Builds up the appropriate internal variables if this select has any Join data.

3) The program determines what kind of query has been passed by the client. If the query is a standard Entry Screen defined by Vantage Application Factory, the program will setup the appropriate internal variables to read/ extract/ update / insert data into the defined files. If the query is a user-defined query, the program may additionally build up a select statement (i.e. Select File with by").  

The server program will then setup all the internal variables required to EXTRACT, UPDATE, and INSERT the data passed by the client.

Element

Description

Number

48

Constant

vxCloseQueryCmd

Input Arguments

2 = Query Handle - The number assigned in the Open Query Process. 

Output Arguments

None

Operation

The server program verifies the query number as a valid and active query. The process unlocks any and all files locked by the query, then cleans up and initializes the internal query variables.

Element

Description

Number

31

Constant

vxBeginTransCmd

Input Arguments

1=Server Handle - The number assigned for this server session.

Output Arguments

1 = Return code - A one (1) if successful, zero (0) if it failed.

Operation

The server program verifies the server number passed is the correct and the active server number. The server will then increment the internal variable TRANSACTION by 1.

Note: during any Update/Insert process, if the variable TRANSACTION is set to any number larger than zero, the file VSSTAGE will be updated (therefore not the real destination file).

Element

Description

Number

32

Constant

vxCommitCmd

Input Arguments

1 = Server Handle - The number assigned for this server session.

Output Arguments

1 = Return code - A value of 1 if the Commit was successful, zero if a failure occurs.

Operation

The server program verifies the server number passed is the correct and active server number. It will then verify that there are transactions outstanding by checking to see if the variable TRANSACTION has a number larger than zero (0) in it.

The server will go through the VSSTAGE file, selecting the records for this connection, and for this transaction, update the appropriate files/records/fields.

The VSSTAGE file is setup as follows:

Key

Each item in the VSSTAGE file has its item id as any Pick item has. Because the stage file is shared with all users (connections), the key must have the connection number as one of its parts. The stage file may also represent multiple begin transaction levels. Therefore, the key also must have which level of transaction it represents and have the file and record id for that file. The following is an example of a key:

1\2\3\COMPANY

Where:

1        Connection number. This is the first connection.

2        Transaction number. This is the second transaction. In this case, there were two Begin transactions (31) sent by the client.

3        Record Id. This is the record id of the file. In this example, the file name is COMPANY.  This file will be updated.

Item 

The stage item is divided into two parts: The first part is a multi-valued list of the actual attribute numbers to update. The location of each attribute number in the list is important. The location corresponds to where, within the item, the associated data exist.  For example: the first multi-values data will be attribute 2; the second multi-values data will be in attribute 3; and so on.

The second part is where the data is stored. Attributes 2 and up contain the data which will replace the current data (if any) on the file. The following is an example of an item:

001 1 ] 5 ] 10

002 XYZ Company, Inc.

003 Albuquerque

004 10 ] 20 ] 30 ] 40

Where:

Attribute one (1) contains three (3) multi-values.  Using the key defined above, the COMPANY file with the record key of 3 will be updated; attribute 1 will be replaced with the contents of attribute 2 (XYZ Company, Inc.); attribute 5 will be replaced with Albuquerque (contents of attribute 3); and attribute 10 (of the COMPANY file) will be replaced with the multi-valued data of 10]20]30]40.

Element

Description

Number

33

Constant

vxRollbackCmd

Input Arguments

1 = Server Handle - The number assigned for this server session.

Output Arguments

1 = Return code - A value of 1 will be passed if Rollback was successful, zero if a failure occurs.

Operation

The server program verifies the server number passed is the correct and active server number. It will verify that there are transactions outstanding by checking to see if the variable TRANSACTION has a number larger than zero (0) in it.

The server will select the VSSTAGE file with the connection number passed by the client and for the current transaction level (as defined by internal variable TRANSACTION). It will then delete, or remove, the records from the VSSTAGE file and unlock any locks set.  The TRANSACTION variable will be reduced by 1.

Element

Description

Number

11

Constant

vxSelectCmd

Input Arguments

2 = Query Handle - The number assigned in the Open Query Process.

3 = Select Values - A multi-valued list of values matching the Select Fields (Where clauses) of a Query.

Output Arguments

1 = Return code - 0, No records selected; 1, One record returned; -1, Multiple records returned (cursor will be positioned at the first record).

Operation

The server program will verify the query number passed is a valid and the active query. If the file used in the query is not a virtual table, the server program will go through and unlock any previously locked records associated with the current query.

The server will then attempt to select the first record of the query. The record will be retrieved based on how the query was originally. The server may do a simple read or it may select a table (file), reading the first record from the list.  In the case of a virtual table (an correlated list of multi-valued or sub-valued fields), the data is retrieved from the base file.

If no records were found (selected), a 0 will be returned back to the client. If there was a record found, the server will try to retrieve a second record. If it was possible to retrieve another record, the server will return a -1 to the client (reporting multiple records were found). If an additional record was not found, the server will return a 1, indicating a single record was selected.

Element