Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Tools : @MAP

@MAP
Registers and allocates storage for use with MAP tables. (TBL)
Prerequisites
Before you use @MAP, you must define a MAP table using the Table Definer.
See Also
TIBCO Object Service Broker Managing Data for details on defining and using MAP tables.
Parameters
@MAP has the following parameter:
Values for the SCOPE Parameter
@MAP is parameterized by storage scope and location, and different security controls apply to each of the storage scope parameter values.
An insert with a NULL or zero ADDRESS and a positive SIZE allocates and registers memory as requested, and returns its address in @MAP.ADDRESS.
The storage is valid only for the life of the current transaction. Both the storage and the corresponding row in @MAP disappear at transaction end.
An insert with a NULL or zero ADDRESS, and a positive SIZE allocates and registers memory as requested, and returns its address in @MAP.ADDRESS.
The storage is valid for the life of the TIBCO Object Service Broker session, and can be both read and written by the user.
An insert with a NULL or zero ADDRESS, and a positive SIZE allocates and registers memory as requested and returns its address in ADDRESS.
The storage is SESSION storage that is also made known to any external environment (for example, CICS) and is suitable for use as a COMMAREA.
The ADDRESS returned is valid for use as a COMMAREA and can be placed in field COMMHANDLE in the table @SESSION to make this storage into the active COMMAREA.
Any number of COMMAREAs can exist at one time but only the one pointed to by @SESSION is recognized by the external environment.
You can also allocate ENVIRONMENT space in an environment that does not support COMMAREAs.
The storage is not known to, or provided by, TIBCO Object Service Broker storage management. Typically this is storage obtained by an external routine that is communicating with TIBCO Object Service Broker rules. TIBCO Object Service Broker does not validity-check the address of EXTERNAL storage at registration time. Addresses that are invalid can cause rejection or failure when actually used as the argument to a MAP table. What addresses are valid depends on the Execution Environment platform and the current operating environment.
The storage is not known to, or provided by, TIBCO Object Service Broker storage management. Typically this is storage obtained by an external routine that is communicating with TIBCO Object Service Broker rules. TIBCO Object Service Broker does not validity-check the address of EXTERNAL storage at registration time. Addresses that are invalid can cause rejection or failure when actually used as the argument to a MAP table. What addresses are valid depends on the Execution Environment platform and the current operating environment.
Fields
The following are the fields of the @MAP table:
Usage Notes
Inserting a row in @MAP registers a block of storage for use by MAP tables and can also obtain the storage from the TIBCO Object Service Broker storage manager. No explicit function is provided to delete storage (or corresponding rows in @MAP).
Selection is supported on @MAP, as well as the INSERT, GET, and FORALL operations. GET and FORALL retrieve the appropriate rows in ascending KEY order. For more information on these operations as used by MAP tables, refer to TIBCO Object Service Broker Managing Data.
When inserting to @MAP, the value used in the SIZE field does not have to allow for the 4 bytes that appear to be used for the KEY field of the MAP table. For Example, suppose the MAP table has fields as shown in this table:
Each row of the table occupies 5 bytes (not 9 bytes, because the KEY field occupies no physical storage space). Storage should be allocated in multiples of 5 bytes.
@MAP behaves like a session table in that its content and effects are local to one TIBCO Object Service Broker session and are not seen by other users, even if they are sharing a single Execution Environment.
You need to manage the storage you acquire with @MAP. This is especially true for environment and session storage used for programmatically invoked sessions; for example, sessions invoked via the SDKs.
You can reuse storage by having a storage acquisition rule such as the following:

 
GETSESSION(LENGTH);
_
_ ---------------------------------------------------------------
_ ------------------------------------------------------------+--
_ GET @MAP('SESSION') WHERE SIZE >= LENGTH; ¦ 1
_ RETURN(@MAP.ADDRESS); ¦ 2
_ ---------------------------------------------------------------
_ ON GETFAIL @MAP :
_ @MAP.ADDRESS = 0;
_ @MAP.SIZE = LENGTH;
_ INSERT @MAP('SESSION');
_ RETURN(@MAP.ADDRESS);

 
If your application is more complex and requires multiple storage areas, you can use a more complex rule that validates the contents of the storage before returning it for use.
The following is an example from the WMQ interface code that checks to see if a) the length is correct, b) the existing area contains a valid eyecatcher, and c) initializes a new area and eyecatcher if required.

 
@MOMGETMOMMAPA;
_
_ ----------------------------------------------------------------
_ ------------------------------------------------------------+---
_ GET @SESSION(0); ¦ 1
_ GET @MOM_PLATFORM WHERE PLATFORM = @SESSION.PLATFORM; ¦ 2
_ FORALL @MAP('SESSION') WHERE SIZE = @MOM_PLATFORM.MAP_SIZE ¦ 3
_ : ¦
_ GET @MOMMAP(@MAP.ADDRESS); ¦
_ CALL @EQ(@MOMMAP.MANAGER_TYPE, '@MOMMAP'); ¦
_ CALL @EQ(@MOMMAP.MANAGER_TYPE, @MOM_PLATFORM.QUEUEMGR); ¦
_ END; ¦
_ @MAP.SIZE = @MOM_PLATFORM.MAP_SIZE; ¦ 4
_ @MAP.ADDRESS = 0; ¦ 5
_ INSERT @MAP('SESSION'); ¦ 6
_ @MOMMAP.KEY = 1; ¦ 7
_ @MOMMAP.MANAGER_TYPE = '@MOMMAP'; ¦ 8
_ REPLACE @MOMMAP(@MAP.ADDRESS); ¦ 9
_ RETURN(@MAP.ADDRESS); ¦ A
_ ----------------------------------------------------------------
_ ON EQ :
_ RETURN(@MAP.ADDRESS);

 

Exception
 
Example
The following rule uses @MAP to allocate and register 100 bytes of TRANSACTION storage for use with MAP tables. After the INSERT, the system sets the ADDRESS field of the @MAP table to the address of the allocated storage. At transaction end, the storage and the matching row in @MAP are deleted by the system.

 
@MAP_SAMPLE1;
LOCAL P;
---------------------------------------------------------------------------
------------------------------------------------------------+--------------
_ @MAP.ADDRESS=0; | 1
_ @MAP.SIZE=100; | 2
_ INSERT @MAP('TRANSACTION'); | 3
_ P = @MAP.ADDRESS; | 4
_ ---------------------------------------------------------------------------

 
The @MAP_Sample2 Rule
The following rule uses @MAP to register external storage for read-only access by MAP tables. The address (A) and size (S) of the storage block to be registered are passed as arguments to the rule. No storage is allocated by the system; it is the programmer’s responsibility to ensure that the address to be registered is valid and points to the desired data in storage. The registration information is not deleted by the system until the TIBCO Object Service Broker session ends.

 
@MAP_SAMPLE2(A,S);
_
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ @MAP.ADDRESS = A; | 1
_ @MAP.SIZE = S; | 2
_ INSERT @MAP('EXTERNALRO'); | 3
_ ---------------------------------------------------------------------------

 

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved