TCache API

본 장에서는 TCache API의 사용법과 예제에 대해서 설명한다.

1. 개요

다음은 TCache API 목록에 대한 설명이다.

API 설명

pfmTCacheGet

TCache Shared Memory에 Item값을 설정한다.

pfmTCacheGetAll

TCache가 관리하는 cache_name 테이블에 존재하는 모든 레코드 데이터를 mem 버퍼에 size만큼 읽어온다.

pfmTCachePut

TCache가 관리하는 메모리에 데이터를 저장하기 위한 API이다.

pfmTCacheInvalidate

TCache가 관리하는 메모리를 초기화하기 위한 API로 cache_name 테이블 내의 Key에 해당하는 레코드 데이터를 초기화한다.

pfmTCacheInvalidateAll

TCache가 관리하는 메모리를 초기화하기 위한 API로 cache_name 테이블 내의 모든 데이터를 초기화한다.

pfmTCacheItem

ProFrame 전용 API로 pfmTCacheGet과 pfmTCachePut이 하나의 기능으로 구현된 부분이다.

2. pfmTCacheGet

TCache Shared Memory에 Item값을 설정한다. TCache에서 데이터를 읽어올 때 READ Lock을 획득해야 한다. No-Wait 모드에서는 한 번의 Lock의 획득 시도를 실패하면 바로 오류를 반환하는 반면 Wait 모드에서는 일정 횟수의 Lock 획득을 시도한 후 실패하는 경우 오류를 반환한다. TCache의 전반적인 수행 능력의 향상을 위하여 기본적으로 flag는 0으로 설정한다.

  • 프로토타입

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

  • 파라미터

    파라미터 설명

    cacheName

    pfmtcache.cfg에서 정의한 “CACHE_NAME”이다.

    key

    입력 데이터의 앞부분부터 pfmtcache.cfg 파일에 기록된 “SIZE_KEY” 길이만큼의 데이터이다.

    mem

    저장된 데이터를 받아올 임시 버퍼이다.

    size

    데이터를 받아올 버퍼의 크기를 설정한다.

    flags

    Blocking Mode를 결정하기 위한 flags이다.

    • 0 : No-Wait(기본값)

    • 1 : Wait

  • 반환값

    성공하는 경우에는 0을 리턴하고, 실패하는 경우에는 negative 값이 리턴된다. 에러 코드에 대한 자세한 내용은 에러 코드를 참고한다.

  • 예제

    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);
}

  • 주의사항

    데이터를 저장할 버퍼인 mem의 크기가 TCache에 존재하는 데이터보다 작을 경우 에러를 반환하지 않고 4번째 인자인 size만큼의 데이터를 받아오며, 정상 리턴하게 된다.

사용 예제

캐시 이름이 PFM_SVC인 경우 “PFM4 ORDERBOOK_SMPF0001_S0010”라는 Key를 가진 데이터를 Get해오는 예제이다.

캐시 Key에 해당하는 데이터가 존재하지 않을 경우 DBIO인 PfmSvcSel000를 이용하여 DB select를 수행하여 가져온 데이터를 PFM_SVC 캐시에 Put해준다.

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 : 정상일때 */
    PFM_TRYNJ( pfmDbioSelect("PFM_SVC_PS0001Output ", &SVCInput, &SVCOutput, NULL,
               PFMDBIO_NOLOCK));
    if( rc != RC_NRM){
       if( rc == PDB_NOTFOUND)  /* 1403L :DB에서 찾지 못했을때 발생 */
           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 : 정상일때 */
         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

TCache가 관리하는 cache_name 테이블에 존재하는 모든 레코드 데이터를 mem 버퍼에 size 만큼 읽어온다.

  • 프로토타입

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

  • 파라미터

    파라미터 설명

    cacheName

    pfmtcache.cfg에서 정의한 “CACHE_NAME”를 설정한다.

    mem

    저장된 데이터를 받아올 임시 버퍼이다.

    size

    데이터를 받아올 버퍼의 크기를 설정한다.

    flags

    • 0 : No-Wait(기본값)

    • 1 : Wait

  • 출력 Layout

    저장된 레코드의 개수(unsigned int : 8byte), record1 크기(unsigned int : 8byte), record 1 데이터, record2 크기(unsigned int : 8byte), record2 데이터, ...

  • 반환값

    성공하는 경우에는 0을 리턴하고, 실패하는 경우에는 negative 값이 리턴된다. 에러 코드에 대한 자세한 내용은 에러 코드를 참고한다.

  • 예제

    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));
}

  • 주의사항

    데이터를 받아올 버퍼가 TCache에 저장된 데이터보다 작을 경우에 에러를 리턴하지 않고 세 번째 인자의 크기만큼 데이터를 받아오며 정상 처리된다. pfmTCacheGetAllItems() API는 Block Mode이므로 pfmTCacheInvalidate()와 같은 Block Mode로 동작하는 API가 자주 호출되는 환경에서는 속도의 저하를 초래할 수 있다.

4. pfmTCachePut

TCache가 관리하는 메모리에 데이터를 저장하기 위한 API이다. cache_name 테이블에서 Key 값에 해당하는 레코드 데이터를 mem 버퍼에 size 만큼 읽어온다.

  • 프로토타입

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

  • 파라미터

    파라미터 설명

    cacheName

    pfmtcache.cfg에서 정의한 “CACHE_NAME”를 설정한다.

    mem

    저장된 데이터를 받아올 임시 버퍼이다.

    size

    데이터를 받아올 버퍼의 크기를 설정한다.

    flags

    • 0 : No-Wait(기본값)

    • 1 : Wait

  • 반환값

    성공하는 경우에는 0을 리턴하고, 실패하는 경우에는 negative 값이 리턴된다. 에러 코드에 대한 자세한 내용은 에러 코드를 참고한다.

  • 예제

    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);
}

  • 주의사항

    저장되는 데이터의 첫 번째 Byte로부터 pfmtcache.cfg에서 “SIZE_KEY”로 설정한 값 만큼의 정보를 TCache의 Key로 이용하므로 Key에 관한 정보가 저장할 데이터의 제일 앞에 위치하도록 한다.

사용 예제

pfmTCacheGet의 예제를 참조한다.

5. pfmTCacheInvalidate

TCache가 관리하는 메모리를 초기화하기 위한 API로 cache_name 테이블 내의 Key에 해당하는 레코드 데이터를 초기화한다.

  • 프로토타입

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

  • 파라미터

    파라미터 설명

    * cacheName

    pfmtcache.cfg에서 정의한 “CACHE_NAME”를 설정한다.

    * key

    입력 데이터의 앞 부분부터 pfmtcache.cfg 파일에 기록된 “SIZE_KEY”길이만큼의 데이터이다.

    size

    데이터를 받아올 버퍼의 크기를 설정한다.

    flags

    invalidate될 때 내부적으로 사용하는 flag로써 기본적으로 “0”으로 설정한다.

  • 반환값

    성공하는 경우에는 0을 리턴하고, 실패하는 경우에는 negative 값이 리턴된다. 에러 코드에 대한 자세한 내용은 에러 코드를 참고한다.

  • 예제

    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);
}
사용 예제

“tb_mti700”이라는 DBIO를 업데이트한 후 동기화를 위해 TCache를 invalidate하는 예제이다.

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", "업데이트에 실패했습니다.");
}
else {
    PFM_DBG("========TCache invalidate==========");
    PFM_TRYNJ(pfmTCacheInvalidate("TB_MTI700", &mti700_ps999In, 0));
    if(rc != RC_NRM) {
         if(rc == RC_NFD) {
              /* TCache 에 캐쉬 데이타가 없는 경우 */
              PFM_DBG("pfmTCacheInvalidate NOT Found");
         }
         else {
               /* TCache invalidate 에러 처리 */
               PFM_ERR("TRE0001021", "pfmTCacheInvalidate ERROR! rc[%ld]", rc);
               return RC_ERR;
         }
   } else {
              PFM_DBG("pfmTCacheInvalidate SUCCESS");
   }
}

6. pfmTCacheInvalidateAll

TCache가 관리하는 메모리를 초기화하기 위한 API로 cache_name 테이블 내의 모든 데이터를 초기화한다.

  • 프로토타입

    long pfmTCacheInvalidateAll( const char* cacheName, long flags )

  • 파라미터

    파라미터 설명

    cacheName

    pfmtcache.cfg에서 정의한 “CACHE_NAME”를 설정한다.

    flags

    invalidate될 때 내부적으로 사용하는 flag로써 기본적으로 “0”으로 설정한다.

  • 반환값

    성공하는 경우에는 0을 리턴하고, 실패하는 경우에는 negative 값이 리턴된다. 에러 코드에 대한 자세한 내용은 에러 코드를 참고한다.

  • 예제

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

7. pfmTCacheItem

ProFrame 전용 API로 pfmTCacheGet과 pfmTCachePut이 하나의 기능으로 구현된 부분이다.

pfmTCacheItem과 연관된 $TCACHECONF는 CALLBACK_NAME 파라미터 값이다. 설정된 CALLBACK_NAME이 GET_SVC_BM("CALLBACK_NAME=GET_PFM_SVC")인 경우를 예를 든다면, pfmTCacheGet했을 때 찾지 못했을 경우 GET_PFM_SVC BM에서에서 데이터를 가져와 pfmTCachePut하는 로직을 처리한다. 이때 DlCall되는 라이브러리는 libGET_PFM_SVC.so.*가 호출된다. BM은 "_WS"가 붙지 않은 라이브러리인 RI 영역의 BM 라이브러리만 Dlcall된다. 따라서 RI/WS 환경일 때에는 RI 영역의 BM만 호출된다. Tmax 6에서는 따로 libtdlcall을 링크하지 않아도 된다.

내부적인 처리 구조로 인해 IN/OUT을 가지는 ProFrame C의 BusinessModule로 제한한다. 해당 BM의 Input 구조체의 size는 SIZE_KEY와 대응되며, Output 구조체의 size는 SIZE_REC와 대응된다. CALLBACK_NAME은 BM의 물리명인 "CALLBACK_NAME=GET_PFM_SVC"로 설정한다.

  • 프로토타입

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

  • 파라미터

    파라미터 설명

    cacheName

    pfmtcache.cfg에서 정의한 “CACHE_NAME”를 설정한다.

    key

    입력 데이터의 앞부분부터 pfmtcache.cfg 파일에 기록된 “SIZE_KEY” 길이만큼의 데이터이다.

    mem

    저장된 데이터를 받아올 임시 버퍼이다.

    size

    데이터를 받아올 버퍼의 크기를 설정한다.

    flags

    Blocking Mode를 결정하기 위한 flags이다.

    • 0 : No-Wait(기본값)

    • 1 : Wait

  • 반환값

    성공하는 경우 0를 반환하고, 실패하는 경우에는 negative 값이 반환된다.

  • 예제

    • pfmtcache.cfg 설정값

      # cache for PFM_SVC
CACHE_NAME=PFM_SVC
SIZE_MEM=6553                # the total cache memory size in kilo-bytes
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);
}