ZCommand

Zcommand is an Interactive Processing Object. It enables access to a ZIM database and has all the capabilities of a Zim multi-user database agent. It can present two different (mutually-exclusive) command interfaces: an operating system command line interface and a ZIM 1202 interface. Zcommand also has the ability to communicate with other ZIM 1202 compatible objects.

Overview

The command line version of the Zim multi-user DB agent (zcommand) has a connector mode of operation that is indicated by using the ’-c’ command line argument. This causes the zcommand instance to listen on the specified port and receive requests over a socket connection. This allows any ZIM 1202 compatible process access to the database that the zcommand has access to.  Like the command line version of zcommand the connector instance relies on environment variables to indicate the working directory, database and Zim install directory location. When started as a connector, Zcommand expects to find a text file called conconf.txt in the database directory; this file contains the password required to maintain a connection to this instance of zcommand.

Unlike the existing ZimDBAgent, the client does not have to have any pre-existing knowledge of the nature of the data stored in the database.  It is possible for the client to get the metadata definitions for the database objects and thereby dynamically construct a model of the data store.

Usage

set ZIM="C:\\Program Files\\Zim\\7.1"

set ZIMDBDIR="D:\\MyDBZim"

set ZIMWORKDIR=" D:/MyDBZim /workdir"

zcommand –c <listen port>

The environment variable ZIM is the ZIM installation directory path. ZIMDBDIR is the path to the database to be accessed and ZIMWORKDIR is the path to the working directory for this connection. Each zcommand instance requires its own working directory; if you need multiple zcommand instances on the same database it is better to use zmultiplex. The Zcommand connector will auto-sense between ZIM 1202 and rootDataObject XML format and respond in kind. Only the ZIM 1202 interaction in explained in this section; the mapping to rootDataObject XML should be evident by examining the XLM schema definition for described previously.

Commands

General Message Construction (To Connector)

ZIM 1202 Field

 Contents

 Notes

SegmentRN

A word or number

Groups together a collection of segment groups.

This should be the same for all segments in the message.

GroupID

The command group indicator

This will group a set or segments into a command set.

SegmentID

A Number

 Each segment should have a different ID number within the group, zero indexed, ascending

SegmentType

Literally CONNECT or COMMAND

The case sensitive word COMMAND or CONNECT.

DataName

 

One of COMMAND or PASSWORD

Use COMMAND for SegmentType COMMAND and use PASSWORD for SegmentType CONNECT.

DataType

A word or number

This will be the SegmentRN for all responses generated by the command.

DataValue

The command arguments

These are the command specific arguments.

 

Specific Commands

Command: CONNECT

Interface: Command Socket

Arguments: The connector password in the DataValue field.

Action: If the CONNECT command is absent from a message or the password in the DataValue field does not match the connector password, then the connection is dropped with no feedback.

 

Command: COMMAND

Interface: Command Socket

Arguments: The command or part command in the DataValue field.

Action: Execute the command

 

Command Execution

A single ZIM 1202 message sent to the zcommand connector may contain zero or more groups of commands and each of these commands may contain many lines. Zcommand processes a message in the following way:

 

Verify the PASSWORD

For each different GroupID

  Process the DataValue fields as if they had been types into a terminal session, including recognizing the line concatenation character ’\’

    Send a message back for each command output set in the Group using the contents of the DataType as the response SegmentRN.

Send a PROMPT message

 

General Message Construction (From Connector)

Each time a prompt would normally be generated by a Zim terminal session (between commands) the zcommand connector will return a message. If the message generated output (a ’list’ command) then the output data is sent in the message. If the command would normally write to the terminal (an output command) then a message containing the output is returned. If the command generated an error then the error is returned. Finally after all commands have been attempted a PROMPT message is returned.

The message that is sent to a subscriber will have the following:

ZIM 1202 Field

 Contents

 Notes

SegmentRN

The DataType field from the COMMAND segment

 Groups together a collection of segment groups.

This should be the same for all segments in the message.

GroupID

The Numeric GroupID

 Each group of related segments (a DB row) will have the same GroupID number

SegmentID

 1 - n

 

Each segment will have a different ID number, one indexed, ascending

SegmentType

One of DATA, STDOUT, STDERR or PROMPT

Literally the word DATA, STDOUT, STDERR or PROMPT

DataName

 

Either OUTPUT or a backing store data specification

If the SegmentType is STDOUT, STDERR or PROMPT this filed will contain the literal OUTPUT.

see below for the construction of a backing store data specification

DataType

Either CHAR or NULL

Literally the word CHAR or the work NULL

DataValue

The first 1024 bytes of the value of the attribute.

The value of the data, Note if the DataType is NULL then the backing store returned NULL for this value.

 

Backing Store Data Specification

Format:

<field name>:<field type>:<length>:<decimals>:<special>

Where

Field name is the name (not the display name) of the field.

Field Type is the data type of the field (ALPHA, VASTINT, VARCHAR, etc).

Length is the length of the field in the database.

Decimals is the number of decimal places in the data.

Special is: READONLY for read–only data, NULLS if the field allows NULL values, NONULLS if the field does not allow NULL values and SEQUENCE if the field is an automatically generated sequence number.

 

Examples:

Phone:ALPHA:18:0:NULLS = A thirty byte APLHA field called Phone that may have a NULL value.

Temp:NUMERIC:6:2:NONULLS = A six byte NUMERIC field with 2 decimal places (xxxx.xx) called Temp that may not contain a NULL value.

Sample Dialog

The `Terminal Session` illustrated in the previous section Protocol->Sample Single Query Interaction was done using a connection to zcommand running as a connector. The client Zim instance defined the following document:

Document Name          FileName

FinanceDatabase_PS    S!amccue!5006

A zcommand was started on the system amccue with the following commands:

set ZIM="C:\\Program Files\\Zim\\7.1"

set ZIMDBDIR="D:\\MyDBZim"

set ZIMWORKDIR=" D:/MyDBZim /workdir"

zcommand –c 5006