TCache APIs

This chapter describes TCache APIs.

1. Overview

The following is the TCache API list.

API Description

pfmTCacheGet

Sets item values in TCache shared memory.

pfmTCacheGetAll

Reads record data saved in the specified table managed by TCache.

pfmTCachePut

Stores data to memory managed by TCache.

pfmTCacheInvalidate

Initializes record data that matches a key in the cache_name table to initialize memory managed by TCache.

pfmTCacheInvalidateAll

Initializes all data in the cache_name table to initialize memory managed by TCache.

pfmTCacheItem

Both sets item values in TCache shared memory (pfmTCacheGet) and stores data to memory managed by TCache (pfmTCachePut). Implemented only for ProFrame C.

2. pfmTCacheGet

Sets item values in TCache shared memory.

  • Prototype

    long pfmTCacheGet( const char* cacheName, const char* key, void* mem,
                   const unsigned long size, long flags )

  • Parameters

    Parameter Description

    cacheName

    "CACHE_NAME" defined in pfmtcache.cfg.

    key

    Data as long as "SIZE_KEY" defined in pfmtcache.cfg from the front of the input data.

    mem

    Temporary buffer to get stored data.

    size

    Size of the buffer to get data.

    flags

    Option to determine blocking mode. To read data from TCache, the READ lock is required. For TCache performance, it is recommended to set this paramter to 0.

    • 0: No-Wait mode. If it fails to get the lock once, the error is returned immediately. (Default value)

    • 1: Wait mode. If it fails to get the lock, the error is returned after trying to get the lock a certain number of times.

  • Return values

    Returns 0 if successful or a negative value If fails. For more information about error code, refer to Error Codes.

  • Example

    rc = pfmTCacheGet("PFM_SVC", data, get_data, sizeof(get_data), 0);
if(rc != 0 ) {
   printf("PFM_SVC pfmTCacheGet() fail!!\n");
}else{
   printf("PFM_SVC [%s] Get success!!\n", get_data);
}

  • Note

    If the size of mem (the 3rd argument) is less than that of data in TCache, as much data as the size value (the 4th argument) is obtained and 0 is returned (an error is not returned).

Example

If the cache name is PFM_SVC, the following gets data with the key of "PFM4 ORDERBOOK_SMPF0001_S0010". If the data does not exist, data obtained by executing database select is put to the PFM_SVC cache by using the PfmSvcSel000 DBIO.

struct PfmSvcSel000In {
    char projectId[LEN_PFMSVCSEL000IN_PROJECTID + 1];
        char instNo   [LEN_PFMSVCSEL000IN_INSTNO    + 1];
        char txCode   [LEN_PFMSVCSEL000IN_TXCODE    + 1];
};
typedef struct PfmSvcSel000In PfmSvcSel000In;

struct PfmSvcSel000Out {
        char instNo[LEN_PFMSVCSEL000OUT_INSTNO + 1];
        char txCode[LEN_PFMSVCSEL000OUT_TXCODE + 1];
        char applySdate[LEN_PFMSVCSEL000OUT_APPLYSDATE + 1];
        char applyStime[LEN_PFMSVCSEL000OUT_APPLYSTIME + 1];
        char applyEdate[LEN_PFMSVCSEL000OUT_APPLYEDATE + 1];
        char applyEtime[LEN_PFMSVCSEL000OUT_APPLYETIME + 1];
        char stopFlag[LEN_PFMSVCSEL000OUT_STOPFLAG + 1];
        char stopSdate[LEN_PFMSVCSEL000OUT_STOPSDATE + 1];
        char stopStime[LEN_PFMSVCSEL000OUT_STOPSTIME + 1];
        char stopEdate[LEN_PFMSVCSEL000OUT_STOPEDATE + 1];
        char stopEtime[LEN_PFMSVCSEL000OUT_STOPETIME + 1];
        char calleeName[LEN_PFMSVCSEL000OUT_CALLEENAME + 1];
        long staType;
        char txName[LEN_PFMSVCSEL000OUT_TXNAME + 1];
        char svcName[LEN_PFMSVCSEL000OUT_SVCNAME + 1];
        char dummySvcName[LEN_PFMSVCSEL000OUT_DUMMYSVCNAME + 1];
        char inStructName[LEN_PFMSVCSEL000OUT_INSTRUCTNAME + 1];
        char inMapName[LEN_PFMSVCSEL000OUT_INMAPNAME + 1];
        char outStructName[LEN_PFMSVCSEL000OUT_OUTSTRUCTNAME + 1];
        char outMapName[LEN_PFMSVCSEL000OUT_OUTMAPNAME + 1];
        char logType[LEN_PFMSVCSEL000OUT_LOGTYPE + 1];
        long apLogProcess;
        long errorLogProcess;
        char traceLogLevel[LEN_PFMSVCSEL000OUT_TRACELOGLEVEL + 1];
        char debugLogLevel[LEN_PFMSVCSEL000OUT_DEBUGLOGLEVEL + 1];
        char traceLevel[LEN_PFMSVCSEL000OUT_TRACELEVEL + 1];
        long threshold;
        long sqlTraceLevel;
};
typedef struct PfmSvcSel000Out PfmSvcSel000Out;

PfmSvcSel000In      SVCInput;
PfmSvcSel000Out     SVCOutput;
memset(&SVCInput, 0x00, sizeof(PfmSvcSel000In));
memset(&SVCOutput, 0x00, sizeof(PfmSvcSel000Out));
memcpy(SVCInput.projectId, "MDS", 6);
memcpy(SVCInput.tx_code, "SPFM0008A001", 24);
memcpy(SVCInput.inst_no, "PFM", 3);

rc = pfmTCacheGet("PFM_SVC", &SVCInput, &SVCOutput,
        (unsigned int)sizeof(PfmSvcSel000Out), 0);
if( rc != RC_NRM){  /* RC_NRM = 0L: Normal */
    PFM_TRYNJ( pfmDbioSelect("PFM_SVC_PS0001Output ", &SVCInput, &SVCOutput, NULL,
               PFMDBIO_NOLOCK));
    if( rc != RC_NRM){
       if( rc == PDB_NOTFOUND)  /* 1403L: Couldn't find from the database */
           PFM_ERR("SvcParamDataNotFound projectId[%s], tx_code[%s], inst_no[%s]",
                    SVCInput.projectId, SVCInput.tx_code, SVCInput.inst_no);
        else
           PFM_ERR("SvcParamTableQueryFail pfmDbioGetErrorNo[%ld],
                    pfmDbioGetErrorString[%s]",
                    pfmDbioGetErrorNo(), pfmDbioGetErrorString());
    }
    else{
     rc = pfmTCachePut("PFM_SVC", &SVCOutput, (unsigned int)sizeof(PfmSvcSel000Out), 0);
     if( rc != RC_NRM)  /* RC_NRM = 0L: Normal */
         PFM_DBG("pfmTCachePutError[%s] rc[%ld]", "PFM_SVC", rc);
      else
         PFM_DBG("pfmTCachePutSuccess [%s]", "PFM_SVC");
    }
}
else{
    PFM_DBG("pfmTCacheHitSuccess [%s]", "PFM_SVC");
}

3. pfmTCacheGetAll

Reads record data saved in the specified table managed by TCache. As much data as the specified size (the 3rd argument) is read to the specified mem (the 2nd argument).

  • Prototype

    long pfmTCacheGetAll( const char* cacheName, void* mem,
                      unsigned long size, long flags )

  • Parameters

    Parameter Description

    cacheName

    "CACHE_NAME" defined in pfmtcache.cfg.

    mem

    Temporary buffer to get stored data.

    size

    Size of the buffer to get data.

    flags

    Option to determine blocking mode.

    • 0: No-Wait mode. (Default value)

    • 1: Wait mode.

  • Output layout

    Number of saved records (unsigned int: 8 bytes), record1 size (unsigned int: 8 bytes), record1 data, record2 size (unsigned int: 8 bytes), record2 data, ...

  • Return values

    Returns 0 if successful or a negative value If fails. For more information about error code, refer to Error Codes.

  • Example

    char * get_data;
char * record_count;
get_data = (char*)malloc(10000);

rc = pfmTCacheGetAll("PFM_SVC", get_data, 10000, 0);
if(rc != 0 ) {
   printf("PFM_SVC pfmTCacheGetAll() fail!!\n");
}else{
   printf("PFM_SVC GetAll success!!\n");
   memcpy(&record_count, get_data, sizeof(unsigned int));
   printf("PFM_SVC Get Record Count[%ld]\n", record_count));
}

  • Note

    If the size of mem (the 2nd argument) is less than that of data in TCache, as much data as the size value (the 3rd argument) is obtained and 0 is returned (an error is not returned).

    Since this API is used in blocking mode, performance may decrease if APIs used in blocking mode, such as pfmTCacheInvalidate(), are frequently called.

4. pfmTCachePut

Stores data to memory managed by TCache. As much record data as the specified size (the 3rd argument) is read from the cacheName table (the 1st argument) to the specified mem (the 2nd argument).

  • Prototype

    long pfmTCachePut( const char* cacheName, void* mem,
                   const unsigned long size, long flags )

  • Parameters

    Parameter Description

    cacheName

    "CACHE_NAME" defined in pfmtcache.cfg.

    mem

    Temporary buffer to get stored data.

    size

    Size of the buffer to get data.

    flags

    Option to determine blocking mode.

    • 0: No-Wait mode. (Default value)

    • 1: Wait mode.

  • Return values

    Returns 0 if successful or a negative value If fails. For more information about error code, refer to Error Codes.

  • Example

    rc = pfmTCachePut("PFM_SVC", set_data, sizeof(set_data), 0);
if(rc != 0 ) {
   printf("PFM_SVC pfmTCachePut() fail!!\n");
}else{
   printf("PFM_SVC [%s] Put success!!\n", set_data);
}

  • Note

    From the first byte of the data to be saved, as much data as the value set in "SIZE_KEY" in pfmtcache.cfg is used as a TCache key. Therefore, information about the key must be located in the front of data to save.

Example

Refer to the example in pfmTCacheGet.

5. pfmTCacheInvalidate

Initializes record data that matches a key in the cache_name table to initialize memory managed by TCache.

  • Prototype

    long pfmTCacheInvalidate( const char* cacheName, const char* key, long flags )

  • Parameters

    Parameter Description

    * cacheName

    "CACHE_NAME" defined in pfmtcache.cfg.

    * key

    From the first byte of input data, as much data as the value set in "SIZE_KEY" in pfmtcache.cfg.

    size

    Size of the buffer to get data.

    flags

    Flag internally used for invalidation. Set to 0 by default.

  • Return values

    Returns 0 if successful or a negative value If fails. For more information about error code, refer to Error Codes.

  • Example

    rc = pfmTCacheInvalidate("PFM_SVC", inv_data, sizeof(inv_data), 0);
if(rc != 0 ) {
   printf("PFM_SVC pfmTCacheInvalidate() fail!!\n");
}else{
   printf("PFM_SVC [%s] Invalidate success!!\n", inv_data);
}
Example

The following invalidates TCache for synchronization after updating DBIO named "tb_mti700".

tb_mti700_pu999In   mti700_pu999In;
bzero(&mti700_pu999In, sizeof(tb_mti700_pu999In));
mti700_pu999In.isu_id = 20231;

strncpy(mti700_pu999In.isu_cd, "ks00000000", sizeof(mti700_pu999In.isu_cd));
rc = pfmDbioAmend("tb_mti700_pu999", &mti700_pu999In, NULL, PFMDBIO_NOLOCK);
if(rc != RC_NRM) {
    PFM_ERR("TRE0001020", "Failed to update.");
}
else {
    PFM_DBG("========TCache invalidate==========");
    PFM_TRYNJ(pfmTCacheInvalidate("TB_MTI700", &mti700_ps999In, 0));
    if(rc != RC_NRM) {
         if(rc == RC_NFD) {
              /* No cached data in TCache */
              PFM_DBG("pfmTCacheInvalidate NOT Found");
         }
         else {
               /* TCache invalidation error handling */
               PFM_ERR("TRE0001021", "pfmTCacheInvalidate ERROR! rc[%ld]", rc);
               return RC_ERR;
         }
   } else {
              PFM_DBG("pfmTCacheInvalidate SUCCESS");
   }
}

6. pfmTCacheInvalidateAll

Initializes all data in the cache_name table to initialize memory managed by TCache.

  • Prototype

    long pfmTCacheInvalidateAll( const char* cacheName, long flags )

  • Parameters

    Parameter Description

    cacheName

    "CACHE_NAME" defined in pfmtcache.cfg.

    flags

    Flag internally used for invalidation. Set to 0 by default.

  • Return values

    Returns 0 if successful or a negative value If fails. For more information about error code, refer to Error Codes.

  • Example

    rc = pfmTCacheInvalidateAll("PFM_SVC", 0);
if(rc != 0 ) {
   printf("PFM_SVC pfmTCacheInvalidateAll() fail!!\n");
}else{
   printf("PFM_SVC Invalidate All success!!\n");
}

7. pfmTCacheItem

Both sets item values in TCache shared memory (pfmTCacheGet) and stores data to memory managed by TCache (pfmTCachePut). Implemented only for ProFrame C.

$TCACHECONF related to pfmTCacheItem is the value of the CALLBACK_NAME parameter. For example, when CALLBACK_NAME is set to GET_SVC_BM ("CALLBACK_NAME=GET_PFM_SVC"), if pfmTCacheGet cannot find an item value to set, the data is retrieved from GET_PFM_SVC BM and pfmTCachePut is performed. At this time, the library on which Dlcall is executed is libGET_PFM_SVC.so.*. BM can execute Dlcall only on the RI area’s BM libraries whose name has not "_WS". Therefore, only BM in the RI area is called in an RI/WS environment.

Due to the internal processing structure, use this API only for ProFrame C business modules that have input and output due to internal processing structure. The BM’s input structure size is corresponding to SIZE_KEY, and the output structure size is corresponding to SIZE_REC. Set CALLBACK_NAME to the BM’s physical name, "CALLBACK_NAME=GET_PFM_SVC".

  • Prototype

    long pfmTCacheItem( const char* cacheName, const char* key, void* mem,
                    const unsigned long size, long flags );

  • Parameters

    Parameter Description

    cacheName

    "CACHE_NAME" defined in pfmtcache.cfg.

    key

    From the first byte of input data, as much data as the value set in "SIZE_KEY" in pfmtcache.cfg.

    mem

    Temporary buffer to get stored data.

    size

    Size of the buffer to get data.

    flags

    Option to determine blocking mode.

    • 0: No-Wait mode. (Default value)

    • 1: Wait mode.

  • Return values

    Returns 0 if successful or a negative value If fails. For more information about error code, refer to Error Codes.

  • Example

    • Setting values in pfmtcache.cfg

      # cache for PFM_SVC
CACHE_NAME=PFM_SVC
SIZE_MEM=6553                # the total cache memory size in kilobytes
SIZE_HASH=1024               # the number of hash key (MAX=6553)
SIZE_KEY=30                  # the number of digits of the index column
SIZE_REC=2048                # the size of a single record in bytes
INV_TIMEOUT=10               # invalidation timeout in sec
CALLBACK_NAME=GET_SVC_PARAM  # libGET_SVC_PARAM.so

    • Source Code

      rc = pfmTCacheItem("PFM_SVC", data, get_data, sizeof(get_data), 0);
if(rc != 0 ) {
   printf("PFM_SVC pfmTCacheItem() fail!!\n");
}else{
   printf("PFM_SVC [%s] Get success!!\n", get_data);
}