upostmes

Post an asynchronous message to a Uniface component instance or Uniface Server.

int upostmes(char* Destination, char* MessageId, char* MessageData, char* MessageSource);

The Destination is of the form: {NetworkConnectionString:}InstanceName

The NetworkConnectionString is of the form:

NetworkMnemonic: { HostId }{+PortNumber} |UserName||SymbolicName:InstanceName

Parameters

  • Destination—string defining the component instance that will receive the message.

    • NetworkConnectionString—network connector string to the application running the target instance. If omitted, InstanceName is assumed to be in the current application.
    • InstanceName—name of an instance in the component pool.
    • NetworkMnemonic— three-letter connector code; TCP or TLS.
    • HostId—host name or IP address where the Uniface Router is running. If omitted, the default is localhost ( the current machine). The format of HostID determines the TCP protocol version to be used. For more information, see Host Identification for TCP/IP and TLS.
    • PortNumber—port number on which the Uniface Router is listening. If omitted, the default value is 13001.
    • UserName—user name under which the target application is running
    • SymbolicName—application identifier of an application registered with the Uniface Router
  • MessageId—identifier for the message, which is passed to $msgid in the receiveMessage trigger of the receiving application. MessageId must contain at least one non-blank character and be no more than 32 characters in total.
  • MessageData—data sent with the message, which is passed to $msgdata in the receiveMessage trigger of the receiving application.
  • MessageSource—source of the message, indicating who sent the receiving application. It is passed to $msgsrc in the receiveMessage trigger of the receiving application. If the value is "" or NULL , it defaults to "U3GL".

Return Values

Values Returned by upostmesage

Value

Meaning

0

Success. The message was put in the message queue for the target instance.
-1 The preceding uecreate() was not successful

-12002

Network connection string too long (PM_MAXLOG, 128)

-12009

Message ID too long (PM_MAXMSGDATA, 32)

-12011

Message data too long (PM_MAXMSGDATA, 512)
-12012 Message Source is too long (PM_MAXMSGSRC, 256).

Use

You must first call uecreate() to initialize the Uniface runtime and, if necessary, read the assignment file. If you only use TCP over IPv4, there is no need to specify an assignment file on ucreate().

When using upostmes() in your 3GL program, you must link it with the following DLL's or shared objects:

  • ucall
  • ulib
  • urtl
  • yrtl

Description

upostmes() sends an asynchronous message to a Uniface component instance or Uniface Server via the Uniface Router. The target application must be registered with a local Uniface Router.

upostmes() does codepage conversions on the specified parameters, which are expected to be in the code page specified by $SYS_CHARSET. By first setting $SYS_CHARSET to UTF8, you can send Unicode messages in any language.

The first parameter Destination is the path information that identifies the (local or remote) Uniface Router to send the message to. No password needs to be provided here. The SymbolicName and InstanceName are passed to the Uniface Router so that it can look up the target application in its list of registered applications, and post the message to the correct process. If an instance name is provided, it posts the message to the receiveMessage trigger of that instance. If this instance cannot be found in the application, or if no instance name was provided, it posts the message to the receiveMessage trigger of the application. Note that the colon (:) is mandatory, even if no instance name is provided (see the example below).

Successfully posting a message with upostmes does not guarantee actual delivery of the message. The message will be put on a queue to be picked up by the targeted application or instance. Neither upostmes nor the Uniface Router can determine if and when that will happen.

Posting a Message

The following C program posts a message to the receiveMessage trigger of a remote application with SymbolicName UST and InstanceName COMPONENT.

#include "h3gl.h"
main()
{

  UHACT hEnv;
  long    returnCode;

  /* Initialize Uniface runtime and read an assignment file containing TLS profile ‘tlsprofile’  : */
    returnCode = uecreate(1, 0, 0, "myapp.asn",0,0,&hEnv);

  /* send a postmessage over TCP: */
  returnCode = upostmes("TCP:hostname.domain.com+13001|TheUser||UST:COMPONENT", "MsgIdTCP", "This mësságe was sent over TCP", "My3GLProgram");	
  if (returnCode < 0)
  {
	fprintf (stderr, "Error %d occurred\n", returnCode);
  }

  /* send a postmessage over TLS: */
  returnCode = upostmes("TLS:hostname.domain.com+13002:tlsprofile|TheUser||UST:COMPONENT", "MsgIdTLS", "This message was send over TLS", "My3GLProgram");
  if (returnCode < 0)
  {
	fprintf (stderr, "Error %d occurred\n", returnCode);
  }

  uedelete(hEnv, -1); /* Stop Uniface runtime */
  ufreeh (&hEnv);     /* Free environment handle */	
}

On the machine hostname.domain.com, the Uniface Router must be running on ports 13001 and 13002. User TheUser must have started the application and registered it with the local URouter as UST COMPONENT, like this:

bin\uniface.exe /dnp=tcp:+13001 /ust=UST MyApp

The component instance named COMPONENT in the MyApp application will receive the message. The receiveMessage trigger of the component will be fired, receiving the message ID and text in $msgid and $msgdata, respectively.

Note: The Message API utility provides an executable version of this function on its command line (umsgutil.exe), which is provided on MS Windows platforms in the Uniface bin directory. This program takes command line arguments that correspond to the first three function parameters: /dnp=Destination, /mid=MessageId and /msg=MessageData. For more information, see umsgutil.exe.

Related Topics