ACME Server Messages

The Server communication takes place via PBIO messages.  Each PBIO message must have a defined format.  Defining new messages is covered in the next section.
To use ACMEServer from an application, the simplest way is to use the C/C++, orTcl/Tk interface as described here.  Alternatively, you may decide to use the PBIO/Dataexchange libraries directly and develop your own interface.

The figure below depicts the basic communications architecture:

An application creates a dataexchange and then establishes a connection which creates a dataexchange port (dep) between the application and the server.  Note that although there is only one dep shown in each client, in fact there could be as many as desired since a single dataexchange can support many dep's.

There are two types of predefined messages, which are adequate for most communications with the server. The Basic format consists of a message type and two string parameters, while the Long5 message has a message type and 6 string parameters. It is easy to define more complex messages for specific uses as detailed later.

The table below shows the current message types supported and their parameters. A request is a message sent from the client to the server, while a reply is the message traffic from the server to the client.

Server File Manipulation Messages
Format Message Type Message Description Param1 Param2 Param3 Param4 Param5  Param6
Basic (Request) OPEN This message asks the server to open an existing acme file in the repository. If file is open by another application, you are connected to the same ACME description. Otherwise, the acmelib parses the file and creates a new description. Acme File Name Tool ID NA NA NA NA
Long5 (Request) NEW This message asks the server to create a new ACME system named System name. If the parent name is NULL, this is assumed to be a new top-level system description, otherwise this is created as a subsystem of Parent. Parent may be either a component name or the top-level system name. The type name should be "None" or one of the valid family names (as returned by GET_ALL_FAMILY_TYPES) System Name Parent Name Type Name NULL NULL NULL
Basic (Request) OPEN_FILE_FTP This message alerts the server that the client is beginning the transfer of the file named in param1. The server opens the file of this name in the repository location and prepares to do the save operation. File Name  NULL NA NA NA NA
Basic (Request) FILE_DATA_FTP This alerts the server to store the data being received into filename. The file should have been previously opened via the OPEN_FILE_FTP message. File Name File Data (string) NA NA NA NA
Basic (Request) CLOSE_FILE_FTP This message instructs the server that data transfer is complete. The server closes this file in the repository. File Name NULL NA NA NA NA
Basic (Request) SAVE This message causes the server to export the current ACME description to the client. The current description is saved in File Name in the repository. File Name NULL NA NA NA NA
Basic (Response) SAVE This message is in response to a save request. The server transmits the file back to the requestor a line at a time. Sends DATA_DONE when complete. File Data NULL        
Basic (Request) CLOSE This message will close the current connection. The server will remove the connection from the current connection list. It decrements the reference count of the current description and if 0 removes the description from memory. NULL NULL NA NA NA NA
General Server Responses
Format Message Type Message Description Param1 Param2 Param3 Param4 Param5 Param6
Basic (Response) ACME_SUCCESS  This message is sent after a successful operation by the server. Top System Name(for OPEN_ACME) otherwise NULL Layout file name (for OPEN_ACME) otherwise NULL NA NA NA NA
Basic (Response) ACME_FAILURE This message is sent when the requested action fails. The first parameter may contain additional details about the failure. Error String or NULL NULL NA  NA NA NA
Basic or Long5 (Response)  DATA_DONE This message is always sent to signal the end of a list of items sent by the server. For instance if you have requested a GET_COMPONENTS service, you would get a sequence of 0..n COMPONENT_NAME messages followed by the DATA_DONE message. NULL  NULL NULL NULL NULL NULL
General ACME Structure Messages
Format Message Type Message Description Param1 Param2 Param3 Param4 Param5 Param6
Basic (Request) GET_CONNECTORS This message requests the server to send all connectors for a given system name. System Name NULL NA NA NA NA
Long5 (Response) CONNECTOR_NAME This message is sent for each connector in a system.. The server resolves the attachments and sends the two components to which this connector is attached. Last message will be DATA_DONE. Name NULL NULL From Component Name To Component Name NULL
Basic (Request) GET_COMPONENTS This message requests the server to send all the components in a given system. Last message will be DATA_DONE. System Name NULL NA NA NA NA
Basic (Response) COMPONENT_NAME This message is sent for each component in the system. The representation exists flag is 0xffffff for components with no subsystems and is 0xffff00 if the component has a subsystem. Last message will be DATA_DONE. Name Representation Exists Flag NA NA NA NA
Basic (Request) GET_BINDINGS This message requests the bindings from the server for connectors in the subsystem. The returned connectors (see CONNECTOR_NAME) will have a component in the subsystem and a component in the parent system. (The server resolves all bindings for you). Last message will be DATA_DONE. System Name NULL NA NA NA NA
Basic (Request) GET_PORTS This message will return all the ports associated with a given component in a given system.  Component Name System Name NA NA NA NA
Basic (Response) PORT_NAME This message contains the port names in response to a previous GET_PORTS message. Last message will be DATA_DONE. Port Name NULL NA NA NA NA
Basic (Request) GET_ROLES This message will return the roles (2) of the given connector.  Connector Name System Name NA NA NA NA
Basic (Response) ROLE_NAME This message will return the role names for the requested connector. Last message will be DATA_DONE. Role Name NULL NA NA NA NA
Long5 (Request) NEW_PORT Create a new port for a given component in a given system. If a port by that name already exists for a given component, the server ignores the request. Returns ACME_SUCCESS. New Port Name Component Name System Name NULL NULL NULL
Long5 (Request) NEW_ROLE Create a new role for a given connector in a given system. If a role by that name already exists, the server ignores the request. Returns ACME_SUCCESS. New Role Name Connector Name System Name NULL NULL NULL
Long5 (Request) NEW_ATTACHMENT Adds a new attachment to system System Name. Component Name and Connector Name are both considered to be in system System Name, if not use NEW_BINDING instead. Returns ACME_SUCCESS or ACME_FAILURE based on results. Port Name  Component Name Role Name Connector Name System Name NA
Long5 (Request) NEW_BINDING Adds a new binding from an inner Port on a component to an outer Port on the Parent Component. Returns ACME_SUCCESS or ACME_FAILURE based on results. Outer Port Name Outer Component Name Outer System Name Inner Port Name Inner Component Name Inner System Name
Long5 (Request) NEW_COMPONENT Adds a new Component of Component Type to the System. Use "None" for no type. Returns ACME_SUCCESS or ACME_FAILURE based on results. Component Name System Name Component Type Name NULL NULL NA
Long5 (Request) NEW_CONNECTOR Adds a new Connector of Connector Type to the System. Use "None" for no type. Returns ACME_SUCCESS or ACME_FAILURE based on results. Connector Name System Name Connector Type Name NULL NULL NA
Basic (Request) DELETE_COMPONENT Removes a component from the Acme Description. Returns ACME_SUCCESS or ACME_FAILURE based on results. Component Name System Name NA NA NA NA
Basic (Request) DELETE_CONNECTOR Removes a connector from the Acme Description. Returns ACME_SUCCESS or ACME_FAILURE based on results. Connector Name System Name NA NA NA NA
 Basic(Request) GET_ALL_COMPONENTS  Returns a list of every component in an acme description qualified by system name, for instance sys.subsys.component  System Name NA  NA  NA   NA NA 
Basic(Request) GET_ALL_CONNECTORS Returns a list of every connector in an acme description , qualified by system name.  System Name NA NA NA NA NA
ACME Property Messages
Format Message Type Message Description Param1 Param2 Param3 Param4 Param5 Param6
Long5 (Request) SET_SYSTEM_PROPERTY This message allows the value of a system property to be set. If the property exists, the new value is set. If the property does not exist, a new one is created. Property type can be set to "None" if a default is used. Returns either ACME_SUCCESS or ACME_FAILURE based on result. System Name Property Name Property Type Property Value (as String) NULL NULL
Long5 (Request) SET_COMPONENT_PROPERTY This message allows the value of a component property to be set. If the property does not exist, a new one is created. Property type can be set to "None" if a default is used. Returns either ACME_SUCCESS or ACME_FAILURE based on result. System Name Property Name Property Type Property Value (as String) NULL NULL
Long5 (Request) SET_CONNECTOR_PROPERTY This message allows the value of a connector property to be set. If the property does not exist, a new one is created. Property type can be set to "None" if a default is used. Returns either ACME_SUCCESS or ACME_FAILURE based on result. System Name Property Name Property Type Property Value (as String) NULL NULL
Basic (Request) GET_SYSTEM_PROPERTIES This message retrieves all properties associated with a given system. System Name NULL NA NA NA NA
Basic (Request) GET_COMPONENT_PROPERTIES This message retrieves all properties associated with a given component in a given system. Component Name System Name NA NA NA NA
Basic (Request) GET_CONNECTOR_PROPERTIES This message retrieves all properties associated with a given connector in a given system. Connector Name System Name NA NA NA NA
Long5 (Response) PROPERTY For the above 3 messages, the server returns the set of properties (0..n) associated with the given ACME Element. Property Name Property Type Property Value (as String) NULL NULL NULL
Long5 (Response) SET_PORT_PROPERTY This message allows the value of a port property to be set. If the property does not exist, a new one is created. Property type can be set to "None" if a default is used. Returns either ACME_SUCCESS or ACME_FAILURE based on result. Port Name Component Name System Name Property Name Property Type Property Value (as String)
Acme Type Messages
Format Message Type Message Description Param1 Param2 Param3 Param4 Param5 Param6
Basic (Request) GET_ALL_FAMILY_TYPES Get all the family types defined for this ACME description.. NULL NULL NA NA NA NA
Basic (Response) ACME_SUCCESS A set of family type names returned from server. Last message is a DATA_DONE. Family Type Name NULL NA  NA NA NA
Basic (Request) GET_ALL_COMPONENT_TYPES Get all the component type names defined for the request system. System Name NULL NA NA NA NA
Basic (Response) ACME_SUCCESS A set of component type names returned from server. Last message is a DATA_DONE. Component Type Name NULL NA NA NA NA
Basic (Request) GET_ALL_CONNECTOR_TYPES Get all the connector type names defined for the requested system. System Name NULL NA NA NA NA
Basic (Response) ACME_SUCCESS A set of connector type names returned from server. Last message is a DATA_DONE. Connector Type Name NULL NA NA NA NA
Basic (Request) GET_TYPE_PORTS Get all the port names defined for the requested component type in the named system. Component Type Name System Name NA NA NA NA
Basic (Request) PORT_NAME Port names that correspond to the above request. Last message will be DATA_DONE. Port Name NULL NA NA NA NA
Basic (Request) GET_TYPE_ROLES Get all the role names defined for the requested connector type in the named system. Connector Type Name System Name NA NA NA NA
Basic (Request) ROLE_NAME Role names that correspond to the above request. Last message will be DATA_DONE. Role Name NULL NA NA NA NA
Basic (Request) GET_COMPONENT_TYPE For the requested component in the requested system, return its type. Component Name  System Name NA NA NA NA
Basic (Response) ACME_SUCCESS A component type name returned from server.  Component Type Name NULL NA NA NA NA
Basic (Request) GET_CONNECTOR_TYPE For the requested connector in the given system, return the type of the connector. Connector Name System Name NA NA NA NA
Basic (Response) ACME_SUCCESS A component type name returned from server. Last message is a DATA_DONE. Component Type Name NULL NA NA NA NA

[Next] [Previous] [Table of Contents]