페이지 이력

page no.

Showpageid

📖 이 문서에서 다루는 내용

i-AUD 의 JScript 에서 ServerScript 를 호출하는 두 가지 API - RunScript 와 RunScriptEx 의 사용법을 설명합니다.

이럴 때 이 문서를 읽어보세요:

🗄️ DB 조회·저장 로직을 서버에서 실행하고 싶을 때
📧 메일 발송, 파일 업로드처럼 브라우저에서 직접 할 수 없는 작업을 위임할 때
🔧 여러 보고서에서 공통으로 쓰는 서버 로직을 설계할 때

🔍 두 메서드의 차이
RunScript 와 RunScriptEx 는 거의 동일하지만, 파라미터 전달 여부가 핵심 차이입니다.

	RunScript	RunScriptEx
파라미터 전달	❌ 불가능	✅ params 객체로 전달
사용 시기	전달할 파라미터가 없거나 전역 파라미터만 사용 시	검색 조건, 처리 대상 등 추가 값을 서버에 넘길 때

정보

icon	false
title	💡 권장

특별한 이유가 없다면 RunScriptEx 를 사용하세요.

파라미터가 없을 때는 빈 객체 {} 를 넘기면 됩니다. 나중에 파라미터를 추가해야 할 때 메서드 변경 없이 확장 가능합니다.

📐 API 시그니처

코드 블럭

language	js
firstline	1
title	RunScript / RunScriptEx
linenumbers	true

// 파라미터 없이 호출
Matrix.RunScript(gridNames, scriptName, function(p) {
    if(p.Success == false){
        Matrix.Alert(p.Message);
        return
    }
    var ds = p.DataSet;
});


//파라미터와 함께 호출
Matrix.RunScriptEx("GridName", "ServiceName",{"VS_CODE":"codevalue","VS_NAME":"name value"},  function(p) {
    if(p.Success == false){
        Matrix.Alert(p.Message);
        return
    }
    var ds = p.DataSet;
});

파라미터 요약

파라미터	타입	필수	설명
gridNames	string \| string[]	✅	서버로 전송할 그리드 이름 ( 없으면 "" )
scriptName	string	✅	실행할 서버 스크립트 이름
params	object	RunScriptEx만	서버에 전달할 파라미터
callBack	function	✅	서버 응답 처리 콜백

🎯 scriptName 지정 방식

scriptName 은 어떤 서버스크립트를 실행할지 지정합니다. 세 가지 형식이 있습니다.

패널

borderColor	#ebe0f5
titleBGColor	#efe6f7
title	🔑 핵심 요약

형식	예시	탐색 위치
"스크립트명"	"doSave"	🏠 현재 보고서의 ServerScript
"@스크립트명"	"@COMMON_UTIL"	🏠 현재 보고서의 ServerScript
"@보고서코드@스크립트명"	"@RPT_COMMON@SEND_MAIL"	📂 다른 보고서의 ServerScript

펼치기

title	형식1 - 현재 보고서의 스크립트

현재 보고서의 ServerScript 에서 해당 이름을 찾습니다. 일반적으로 가장 많이 쓰는 방식입니다.

코드 블럭

language	js
firstline	1
title	예제 코드
linenumbers	true

Matrix.RunScriptEx("DataGrid1", "doSave",{},  function(p) {
    if(p.Success == false){
        Matrix.Alert(p.Message);
        return
    }
    var ds = p.DataSet;
});

펼치기

title	형식2 - 보고서 코드 없이 스크립트명만 지정

현재 보고서에 '@' 로 시작하는 이름으로 등록된 스크립트를 호출합니다.

보고서 내부에서만 재사용하는 공통 유틸 스크립트를 관리할 때 사용합니다. (다른 보고서의 스크립트를 호출하려면 형식3을 사용해야 합니다. )

코드 블럭

language	js
firstline	1
title	예제 코드
linenumbers	true

Matrix.RunScriptEx("", "@COMMON_UTIL",{},  function(p) {
    if(p.Success == false){
        Matrix.Alert(p.Message);
        return
    }
    var ds = p.DataSet;
});

펼치기

title	형식3 - 다른 보고서의 스크립트 ⭐

'@보고서코드@스크립트명' 형식은 지정한 보고서에 등록된 서버 스크립트를 호출합니다. 여러 보고서에서 공유할 공통 로직을 한 보고서에 모아두고 관리할 때 사용하는 핵심 패턴입니다.

경고

icon	false
title	⚠️ 반드시 지켜야 할 규칙 - 스크립트 이름 앞에 @ 붙이기

다른 보고서에서 '@보고서코드@스크립트명'으로 호출할 스크립트는 반드시 이름을 '@'로 시작하도록 등록해야 안정적인 참조가 보장됩니다.

코드 블럭

language	js
firstline	1
title	예제 코드
linenumbers	true

Matrix.RunScriptEx("", "@RPT_COMMON@SEND_MAIL",{},  function(p) {
    if(p.Success == false){
        Matrix.Alert(p.Message);
        return
    }
    var ds = p.DataSet;
});

📊 gridNames — 그리드 데이터 전송

DataGrid에서 변경된 데이터를 서버로 함께 넘길 때 지정합니다.. 전송할 데이터가 없으면 빈 문자열 ("") 을 사용합니다.

참고사항

icon	false
title	📝 ServerScript 에서 사용하기

서버 스크립트에서는 req.getDataTable("그리드명") 으로 전달된 데이터를 가져와서 사용합니다.

코드 블럭

language	js
firstline	1
title	예제 코드
linenumbers	true
collapse	true

// 그리드 사용 안함
Matrix.RunScriptEx("", "doSearch", params, callBack);
// 단일 그리드
Matrix.RunScriptEx("GRD_EMPLOYEE", "doSave", params, callBack);
// 복수 그리드 (콤마 구분 또는 배열)
Matrix.RunScriptEx("GRD_MASTER,GRD_DETAIL", "doSave", params, callBack);
Matrix.RunScriptEx(["GRD_MASTER", "GRD_DETAIL"], "doSave", params, callBack);

📦 params — 파라미터 전달
서버 스크립트에 전달할 값을 객체 형태로 지정합니다.

코드 블럭

language	js
firstline	1
title	예제 코드
linenumbers	true
collapse	true

var params = {
    VS_DEPT_CODE: "D001",
    VN_YEAR: 2025,
    VS_FROM_DATE: "2025-01-01",
    VS_TO_DATE:   "2025-12-31"
};
Matrix.RunScriptEx("", "doSearch", params, function(p) {
    if(p.Success == false){
        Matrix.Alert(p.Message);
        return
    }
    var ds = p.DataSet;
});

코드 블럭

language	js
firstline	1
title	서버에서는 아래와 같이 값을 받아서 사용합니다
linenumbers	true
collapse	true

var req = Matrix.getRequest();
var vsDeptCode = req.getParam("VS_DEPT_CODE");  // → "D001"
var vnYear     = req.getParam("VN_YEAR");        // → "2025"

🔄 콜백 처리
서버 처리가 끝나면 콜백 함수가 실행됩니다. 콜백 인자 p 는 세 속성을 가집니다.
속성 타입 설명
p.Success boolean ✅/❌ 서버 처리 성공 여부
p.Message string 💬 실패 시 오류 메시지
p.DataSet DataSet 📦 서버에서 반환한 데이터셋

🏗️ 공통 서버 스크립트 패턴

여러 보고서에서 동일하게 필요한 로직(메일 발송, 파일 업로드, 사용자 검증 등)을 하나의 전용 보고서에 모아두고 '@보고서코드@스크립트명' 으로 호출하는 방식입니다.

패널

borderColor	#ebe0f5
titleBGColor	#efe6f7
title	📂 전체 구조 예시

[공통 서비스 보고서 RPT_COMMON]

ServerScript/

@SEND_MAIL.ts ← 이름이 @로 시작 → 서버에 @SEND_MAIL.jsx로 저장
@UPLOAD_FILE.ts ← 서버에 @UPLOAD_FILE.jsx로 저장
@VALIDATE_USER.ts ← 서버에 @VALIDATE_USER.jsx로 저장

[업무 보고서 RPT_EMP_MGMT]
→ Matrix.RunScriptEx("", "@RPT_COMMON@SEND_MAIL", ...)
→ Matrix.RunScriptEx("", "@RPT_COMMON@UPLOAD_FILE", ...)
[업무 보고서 RPT_ORDER_MGMT]
→ Matrix.RunScriptEx("", "@RPT_COMMON@SEND_MAIL", ...)
→ Matrix.RunScriptEx("", "@RPT_COMMON@VALIDATE_USER", ...)

패널

borderColor	#efe6f7
titleBGColor	#ebe0f5
title	📎 공통 스크립트 include

같은 보고서 또는 다른 위치의 스크립트를 현재 스크립트에 인라인으로 포함합니다.

코드 블럭

language	js
firstline	1
title	예제 코드
linenumbers	true

var// req현재 = Matrix.getRequest();
var vsDeptCode = req.getParam("VS_DEPT_CODE"); 보고서 폴더의 @COMMON_UTIL.jsx 를 포함
<% @include file="@COMMON_UTIL" %>
// → "D001"
var vnYear     = req.getParam("VN_YEAR");        // → "2025"SERVER_SCRIPT 폴더 기준 절대 경로로 포함
<% @include file="/RPT_COMMON/@VALIDATE_USER" %>

참고사항

icon	false
title	🔍 제약 사항

📏 최대 100 단계까지만 include 가 가능하며, 이를 초과하면 오류가 발생합니다.

🔁 동일한 파일을 반복해서 include 하는 경우 자동으로 차단하여 순환 참조를 방지합니다.

🚫 보안상 '../' 경로는 사용할 수 없으며, 사용 시 오류가 발생합니다.

🤫 include 대상 파일이 없을 경우에도 오류는 발생하지 않으며, 해당 부분은 빈 내용으로 처리됩니다.

❓ 자주 묻는 질문 (FAQ)

펼치기

title	🤔 Q. 보고서 코드는 어디서 확인하나요?

가장 간단한 방법은 i-AUD 디자이너에서 파일 다이얼로그를 열고, 헤더 영역에서 마우스 오른쪽 버튼을 클릭한 후 ‘코드’ 옵션을 활성화하여 확인하는 것입니다.

펼치기

title	🤔 Q. 콜백이 실행되지 않을 때 원인은?

다음 순서로 점검해보세요:

1. ✅ scriptName 오타 확인 (보고서 코드나 스크립트명 불일치)

2. 🚀 공통 스크립트 보고서가 서버에 배포되어 있는지 확인

3. 🔍 서버 스크립트에서 예외 발생 → AUD.log 확인

4. 🔑 @로 시작하는 이름으로 등록되어 있는지 확인

펼치기

title	🤔 Q. 서버 오류를 클라이언트에서 받으려면?

서버에서 Matrix.ThrowException("메시지") 를 호출하면 콜백의 p.Success === false, p.Message 에 내용이 전달됩니다.

코드 블럭

language	js
firstline	1
title	ServerScript
linenumbers	true

Matrix.ThrowException("권한이 없습니다.");

코드 블럭

language	js
firstline	1
title	JScript
linenumbers	true

Matrix.RunScriptEx("", "doAction", params, function(p) {
    if (!p.Success) {
        Matrix.Alert(p.Message);  // "권한이 없습니다."
        return;
    }
});

펼치기

title	🤔 Q. params 에 배열이나 객체를 넘기려면?

getParam() 은 항상 문자열을 반환하므로, 복잡한 타입은 JSON.stringify 로 직렬화해서 넘기고 서버에서 파싱합니다.

코드 블럭

language	js
firstline	1
title	JScript
linenumbers	true

Matrix.RunScriptEx("", "doProcess", {
    VS_ITEMS: JSON.stringify([{ id: 1, name: "A" }, { id: 2, name: "B" }])
}, callBack);

코드 블럭

language	js
firstline	1
title	ServerScript
linenumbers	true

var vsItems = req.getParam("VS_ITEMS");         // 문자열로 수신받고
var items   = JSON.parse(vsItems);              // 배열로 변환변환해서 사용!
for (var i = 0; i < items.length; i++) {
    var item = items[i];
    // item.id, item.name 사용
}

펼치기

title	🤔 Q. 서버 스크립트 실행 중 로그를 남기려면?

Matrix.WriteLog() 를 사용합니다. 서버 로그 파일에 기록됩니다.

코드 블럭

language	js
firstline	1
title	ServerScript
linenumbers	true

Matrix.WriteLog("처리 시작: " + vsUserId);
Matrix.WriteLog("SQL 결과 건수: " + tResult.getRowCount());

try {
    // ...
} catch(e: any) {
    Matrix.WriteLog("오류 발생", e);   // 스택 트레이스까지 로그에 기록
    Matrix.ThrowException(e.message);
}

🔗 관련 문서

패널

borderColor	#dbdcde
bgColor	#F4F5F7
title	📚 함께 읽으면 좋은 문서

👉🏻 [i-AUD] 서버 스크립트 호출 시 파라미터를 함께 등록하는 API가 추가되었습니다.

👉🏻 4-9. i-AUD 보고서 세션 변수, 전역 변수 사용방법

👉🏻 [FileDialog] 보고서 코드 설정 기능

👉🏻 Log Viewer

👉🏻 사용자별 로그 분리

👉🏻 Server Script

👉🏻 Client Script

기능 정보

API Open

UI Open

Read Only

Not Use

Hidden

Not Recommend

해당 없음

시작 버전 정보

페이지 속성

hidden	true

정보

title	샘플 BCRM 정보

샘플 URL :
샘플 파일

첨부 파일

patterns	.jsp,.zip,.xml,.js,.mtsd,.xlsx,.xlsb,.mtzb,.mtvx,.mtx,.mtxz,.mtsz

정보

title	BCRM 정보

(BCRM#G1981) 서버스크립트를 공통으로 사용하는 방법 문의

공간 바로가기

페이지 트리

버전 비교

이전 버전 1

새 버전 현재

키

🔍 두 메서드의 차이
RunScript 와 RunScriptEx 는 거의 동일하지만, 파라미터 전달 여부가 핵심 차이입니다.

📐 API 시그니처

🎯 scriptName 지정 방식

📊 gridNames — 그리드 데이터 전송

📦 params — 파라미터 전달
서버 스크립트에 전달할 값을 객체 형태로 지정합니다.

🔄 콜백 처리
서버 처리가 끝나면 콜백 함수가 실행됩니다. 콜백 인자 p 는 세 속성을 가집니다.

🏗️ 공통 서버 스크립트 패턴

속성	타입	설명
p.Success	boolean	✅/❌ 서버 처리 성공 여부
p.Message	string	💬 실패 시 오류 메시지
p.DataSet	DataSet	📦 서버에서 반환한 데이터셋

공간 바로가기

페이지 트리

페이지 이력

버전 비교

이전 버전 1

새 버전 현재

키

🔍 두 메서드의 차이RunScript 와 RunScriptEx 는 거의 동일하지만, 파라미터 전달 여부가 핵심 차이입니다.

📐 API 시그니처

🎯 scriptName 지정 방식

📊 gridNames — 그리드 데이터 전송

📦 params — 파라미터 전달서버 스크립트에 전달할 값을 객체 형태로 지정합니다.

🔄 콜백 처리서버 처리가 끝나면 콜백 함수가 실행됩니다. 콜백 인자 p 는 세 속성을 가집니다.

🏗️ 공통 서버 스크립트 패턴

🔍 두 메서드의 차이
RunScript 와 RunScriptEx 는 거의 동일하지만, 파라미터 전달 여부가 핵심 차이입니다.

📦 params — 파라미터 전달
서버 스크립트에 전달할 값을 객체 형태로 지정합니다.

🔄 콜백 처리
서버 처리가 끝나면 콜백 함수가 실행됩니다. 콜백 인자 p 는 세 속성을 가집니다.