Messaging Layer Prolog API (Version 1.20) ========================================= The "messaging" module includes funtionalities of the "message_format" and "transport" modules. It is recommended to use either the "message_format" or "transport" directly if you do not need all the API predicates. The "messaging" module is maintained mainly for backward compatibility with previous API release. Intialization & Shutdown ------------------------ 1. Initialize Messaging Layer init_messaging(Parameters_with_value) Initialize the messaging layer and get ready for communication. "Parameters_with_value" is a list of parameters with values specific to the communication platform. It is in the form: [arg1:value1, arg2:value2, ...]. Supported arguments: server_host: host name of Linda server *** This is a compulsory argument. server_port: port no. of Linda server *** This is a compulsory argument. id: The Id generator mode, which is one of "counter/random/very_random". If the mode is not specified, the default mode is the un-randomized random no. generator. i.e. everytime it starts, it generates the same sequence of random numbers. The "counter" mode generates incrementing integers starting from 1. The "random" mode uses the "second" part of the system timer to initialize the random number generator. The "very_random" mode uses the "micro-second" part of the system timer to initialize the random number generator. acknowledgement: Specify the acknowledgement timeout value. A missing "acknowledgement" or a value of 0 means no acknowledgement. An integer value N means the message sender will wait for N seconds before it times out. 2 Shutdown the Messaging Layer halt_messaging Stop the Messaging layer. Message Composition & Manipulation ---------------------------------- 1. Contextual-info Composition compose_context( ?Version, ?Conv_id, ?Origin, ?Destination, -Time_stamp, -Context) Compose the message contextual-info from given components or build a template for receiving messages. When composing a message, "Conv_id" should be instantiated. The programmer has the freedom to use anything for "Conv_id". If "Conv_id" is left uninstantiated, it will be filled in by calling "generate_id/1" when the message is sent. In composing a message matching template, "Conv_id" can be left uninstantiated. For most cases, "Time_stamp" should be left uninstantiated. It will be filled in when the message is sent. 2. CCQL Message-core Composition compose_ccql_core( ?Performative, -Arguments, -Core) Compose the CCQL message-core from given components or build a template for receiving messages. "Arguments" is a list in the form: [arg1:value1, arg2:value2, ...] If the message is used as a receiving template, it is suggested to leave "Arguments" uninstantiated. 3. Message Composition compose_message(?Context,?Core,-Message) Compose a message from the contextual-info and the message-core. "Message" is the message composed. "Context" is the contextual-info composed by compose_context/6. "Core" is the message-core composed by compose_ccql_core/5. compose_message( ?Original, ?Destination, ?Performative, ?Arguments, -Message) This is a handy way of composing a message from the major CCQL components with most information filled in by the system. "Original" and "Destination" are the original and destination names in the contextual part. They DO NOT correspond to the sender & reciever argument in the CCQL message core, although in most cases they should be the same. The programmer should set the appropriate sender & receiver values in the argument list by "set_argument/2/3". 4. Message Decomposition decompose_message( ?Context, ?Core, +Message) Decompose a message into the contextual-info & CCQL message-core. decompose_message( ?Original, ?Destination, ?Performative, ?Arguments, +Message) Decompose a message into the corresponding CCQL message components. "Arguments" is a list in the form: [arg1:value1, arg2:value2, ...] As in compose_message/5, "Original" & "Destination" correspond to the values in the contextual-info part. To get the sender & receiver value in the CCQL message core, "use get_argument/2". 5. Contextual-info Decomposition decompose_context( ?Version, ?Conv_id, ?Origin, ?Destination, ?Time_stamp, +Context) Decompose a contextual-info part into the corresponding components. 6. CCQL Message-core Decomposition decompose_ccql_core( ?Performative, ?Arguments, +Core) Decompose a CCQL message-core into the corresponding CCQL components. 7. Generate a Conversational-ID generate_id(-Id) Generate an integer which can be used as an ID. The generator mode is determined by the "id" parameter when calling "init_messaging/1". Message Sending & Receiving --------------------------- 1. Send a Message send_message(+Message) Send a message composed by compose_message/5 or /6. 2. Receive a Message receive_message(?Message_template) Receive a message matching the message-template. "Message_template" is a message composed by composed_message/5 or /6 specifying the receiving criteria. This API blocks until a matching message is received. receive_message(My_name,-Message) Given the agent's name, receive a message targetted to it. This is a preferred API over "receive_message/1". This API blocks until a matching message is received. Instead of customising the receive-template, an agent should accept all messages sent to it and handle them appropriately. Selective receiving is not supported by all communication mechanism and is discouraged. 3. Receive a Message without blocking receive_message_noblock(?Message_template) Receive a message matching the message-template without blocking. "Message_template" is a message composed by composed_message/5 or /6 specifiying the matching template. receive_message_noblock(My_name,-Message) Similary to "receive_message/2" but without blocking. Getting/Setting Argument Value ------------------------------ 1. Get Argument Value get_argument(+Source,?Template) Get argument value(s) from either a message or an argument-list. "Source" can be a message (i.e. contextual + core) or an argument-list decomposed from a message. The matching "Template" can be a "arg:value" pair or a list of "arg:value" pairs. 2. Set Argument Values set_argument(+Value_pairs,-Argument_list) Create a new argument-list from the "Value_pairs". "Value_pairs" can be a single "arg:value" or a list in the form: [arg1:value1, arg2:value2, ...] set_argument(Old_args,Values,New_args) Update argument value in "Old_args" to give the new list "New_args". As in set_argument/2, "Values" can be a single "arg:value" pair or a list in the form: [arg1:value1, arg2:value2, ...].