XScript 매뉴얼 · Chapter 51

SN 객체 — 시리얼 번호 규칙 관리

스크립트에서 키워드 SN 으로 접근. 라벨 인쇄, MES 보고, 트레이싱 등에 사용하는 고정 영역(Lot/Line) + 가변 영역(시퀀스) 시리얼 번호를 규칙 단위로 등록·생성·관리합니다.

개념	설명
규칙(rule)	이름으로 식별. 한 프로젝트에 여러 규칙을 동시에 운영 가능
포맷	`[고정폭:타입:정렬]&[필드::길이]\|[가변영역]` 형태 — 예: `[12:0:Left]&[Lot::6]
컨텍스트	`LotNo` · `LineNo` · `WorkOrderNo` · `SubLot` 4 개 키
제외 문자	기본값 `"1,0,D,I,O"` (사람 눈으로 헷갈리는 문자 제외)

한 줄 요약 — SN.RegisterRule(...) 으로 등록 → SN.SetContext(...) 로 Lot 채움 → SN.GenerateNext(...) 로 다음 시리얼 발급.

1) 규칙 등록 / 갱신

이름 + 풀 포맷 문자열로 한 줄에 등록.

// 풀 포맷 직접 입력
SN.RegisterRule("prodA", "[12:0:Left]&[Lot::6]|[SN:SequencialDecimal:0:6]");
 
// 등록 여부 확인
if( SN.GetRule("prodA") == null )
{
    LogError("rule register failed");
    return false;
}

이미 같은 이름의 규칙이 있으면 덮어씁니다 — 기존 순차 카운터는 유지되지 않고 재초기화됩니다.

2) 컨텍스트 채우기

생성 시 시리얼에 합쳐질 외부 값들을 채워둡니다.

SN.SetContext("prodA", "LotNo",       "LOT2026");
SN.SetContext("prodA", "LineNo",      "L1");
SN.SetContext("prodA", "WorkOrderNo", "WO001");
SN.SetContext("prodA", "SubLot",      "S01");

유효 키: "LotNo", "SubLot", "LineNo", "WorkOrderNo" (그 외 키는 false 반환).

3) 다음 시리얼 발급

string sn = SN.GenerateNext("prodA");
if( sn == "" )
{
    LogError("generate next failed");
    return false;
}
Log($"new SN : {sn}");
// 예) "12LOT2026000001"

GenerateNext 호출은 순차 카운터를 1 증가 시키고 새 값을 반환합니다.

증가 없이 현재 값만 보기

string current = SN.Peek("prodA");   // 마지막으로 발급한 가변영역 값

카운터 초기화

SN.ResetSequence("prodA");           // 규칙 정의는 유지, 가변영역만 리셋

4) 미리보기 / 일괄 생성

Preview — 상태 변경 없음

// 라벨 디자이너 / 검수 화면에서 보여주기 위한 샘플 5개 (실제 카운터는 안 늘어남)
string[] samples = SN.Preview("prodA", 5);

GenerateBatch — 카운터 증가 + 일괄

// 인쇄기에 한 번에 100 매 발급
string[] batch;
if( SN.GenerateBatch("prodA", 100, batch) == false )
{
    LogError("batch failed");
    return false;
}
for(i, 0, batch.Length - 1)
{
    PRINTER.PrintLabel(batch[i]);
}

5) 제외 문자 (ExcludedChars)

가변영역에서 시리얼에 사용하지 않을 문자 를 쉼표 구분으로 지정.

// 기본값(설정 안 했을 때) : "1,0,D,I,O"
string current = SN.GetExcludedChars("prodA");
Log($"excluded : {current}");
 
// 변경
SN.SetExcludedChars("prodA", "1,0,O");
 
// 제외 없음
SN.SetExcludedChars("prodA", "");

I/O 같이 0/1 과 헷갈리는 문자를 제외하면 인쇄·OCR 의 오인식이 크게 줄어듭니다.

6) 규칙 삭제 / 목록

// 등록된 규칙 이름 배열
string[] names = SN.GetRuleNames();
for(i, 0, names.Length - 1) Log(names[i]);
 
// 단일 삭제
SN.RemoveRule("prodA");

7) 영속화 — 파일·프로젝트 저장/불러오기

규칙 정의는 JSON 으로 직렬화됩니다. 가변영역 카운터는 저장 대상이 아님 — 운영 중에만 메모리에 유지됩니다.

// 파일 단위
SN.SaveToFile("D:/Backup/rules.json");
SN.LoadFromFile("D:/Backup/rules.json");
 
// 프로젝트 폴더 기본 경로 (SerialRules.XDF)
SN.SaveToProject();
SN.LoadFromProject();

LoadFromXxx 는 호출 직전 현재 매니저를 비우고 새로 채웁니다. 같은 이름 규칙을 보존하려면 호출 전 미리 export 하세요.

자주 쓰는 패턴

라인 시작 시 — Lot 등록 후 첫 시리얼

FUNCTION OnLotStart(string lotNo, string subLot)
{
    SN.SetContext("prodA", "LotNo",  lotNo);
    SN.SetContext("prodA", "SubLot", subLot);
    SN.ResetSequence("prodA");      // 새 Lot 이면 카운터 재시작
 
    string firstSn = SN.GenerateNext("prodA");
    Data::CurrentSN = firstSn;
    return true;
}

신규 프로젝트 첫 부팅에서 규칙 자동 등록

FUNCTION OnInit()
{
    if( SN.LoadFromProject() == false )
    {
        // 파일이 아직 없으면 코드로 기본 규칙 등록 후 저장
        SN.RegisterRule("prodA", "[12:0:Left]&[Lot::6]|[SN:SequencialDecimal:0:6]");
        SN.SetExcludedChars("prodA", "1,0,D,I,O");
        SN.SaveToProject();
    }
    return true;
}

프리뷰 → 사용자 확인 → 실제 발급

string[] sample = SN.Preview("prodA", 3);
string msg = $"Sample: {sample[0]} / {sample[1]} / {sample[2]}\nProceed?";
if( ShowMessage(EB_YesNo, 0, msg) == ER_Yes )
{
    string real = SN.GenerateNext("prodA");
    // ... print or report
}

함수 한눈 요약

분류	함수
등록 / 조회	`RegisterRule(name, fullFormat)` · `GetRule(name)` · `GetRuleNames()` · `RemoveRule(name)`
컨텍스트	`SetContext(name, key, value)` (`LotNo`/`SubLot`/`LineNo`/`WorkOrderNo`)
제외 문자	`SetExcludedChars(name, chars)` · `GetExcludedChars(name)`
발급	`GenerateNext(name)` · `Peek(name)` · `ResetSequence(name)` · `Preview(name, count)` · `GenerateBatch(name, count, ref array)`
영속화	`SaveToFile(path)` · `LoadFromFile(path)` · `SaveToProject()` · `LoadFromProject()`